Step 1: Make a POST request

To get an authentication token, make a POST request to the following URL: https://api.mastersales.com/v1/{InstanceName}/user/login

Step 2: Provide Basic Authentication

Add an "Authorization" header to your request with the value "Basic {Base64 encoded username and password}". The {Base64 encoded username and password} is the Base64 encoded value of your username and password, separated by a colon.

Step 3: Send the Request

Make sure the Content-Type is set to application/json in your headers and send the request.

POST
https://api.mastersales.com/v1/4/user/login
Headers: 
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/json

Request Body:
{}

                

Step 4: Receive the authentication token

Upon success, you'll receive status code 200 OK, and the response body will contain your JWT token and refresh token.

Example Response:
Status Code: 200 OK
{
    "tokenType": "Bearer",
    "token": "Your JWT Token",
    "expires": "",
    "refreshToken": "Your Refresh Token"
}
                

Prepare the request

Add the Authorization JWT token to the header Authorization and set the Content-Type to application/json

Make a GET request to https://api.mastersales.com/v1/instanceid/account .

Receiving the Response

If the GET request is successful, you should recieve a 200 OK status code. The response will be a collection of resources.

Understanding the Response

The response is a JSON object which contains an items array. Each element in the items array is a data object which contains the fields from a bussiness object, in this example account details like Accountname, Accountnumber, Accounttype.

{
    "items": [
        {
            "data": {
                "Accountgroup": null,
                "Accountname": "John Dow",
                "Accountnumber": 1234,
                "Accounttype": 1,
            }
        },
        ...
    ]
}
                    

Set the Request

URL format: {{base_url}}/{{ApiVer}}/{{InstanceId}}/item.

This is a POST request which is used to create a new item in your database.

Set the Headers

In the headers section, key in Authorization in the Key field and Bearer your_token in the Value field.

Set the Body

Now set the body of the request: In this request we define the SKU and Name for a new item.

                        {
                            "sku": "80000",
                            "Name": [
                                {
                                    "DimensionId": 1,
                                    "FieldValue": "test sync DE"
                                }
                            ]
                        }
                    

Click "Send" or "Apply" to create your new item.

Prepare Delete Request

Prepare your HTTP DELETE request to the appropriate endpoint. The PATH includes the base_url, API version (ApiVer), InstanceID and item ID that you want to delete.

Step 2: Set the Authorization Header

Set the Authorization header in your request to include your authorization token.

Step 3: Send the Request

Once everything is set up correctly, you can send the request. If successful, you should get a status code 200 as response.

Step 1: Prepare Delete Request

Prepare your HTTP DELETE request to the appropriate endpoint. The PATH includes the base_url, API version (ApiVer), InstanceID and item ID that you want to delete.

Step 2: Set the Authorization Header

Set the Authorization header in your request to include your authorization token.

Step 3: Send the Request

Once everything is set up correctly, you can send the request. If successful, you should get a status code 200 as response.

Step 1: Set Headers

Start by setting your headers. This includes providing your Authorization token.

Step 2: Define the Body

Next, define the body of the request in a JSON format. Here you can set the "sku", and then define an array of "Name" objects. Each of these objects should have a "DimensionId" and a "FieldValue". Example:

Step 3: Send the Request

Once you've set the headers and defined the body of your request, you can send it to the appropriate endpoint as defined in your API documentation.

URL Pattern for Single Field Retrieval

If you only need to obtain specific fields of a certain business object, follow this URL pattern:

Here's what each placeholder in the URL stands for:

• {version}: Your api version.
• {InstanceName}: Your MasterSales instance name.
• {BO}: The name of the business object you wish to access.
• {Field}: Function name utilized to fetch a list of fields.
• {ResourceID}: The ID of the resource you wish to access (Optional).

Example Request

Here's an example of how you should implement this request:

Example Response

If executed correctly, the server should return a 200 OK status, along with the specified fields.

                
Status Code: 200 OK 
[ 
    {
        "items": [
            {
                "data": {
                    "FieldName1": "John Dow",
                    "FieldName2": 1234
                }
            },
            ...
        ]
    } 
]
                
                

GET Request - API Usage

You can retrieve specific fields by performing a GET request. Here's how you can form the request:

Where:

• {InstanceName} is the name of your MasterSales instance.
• {BO} is the name of the business object you want to access.
• {Field} is the name of the field you want to retrieve.

Example Request:

Example Response:

Adjusting Number of Rows - rows()

You can manipulate the total number of rows returned in each data pull by using the "rows" parameter. Here is how to manipulate it:

Replace "50" with the number of rows you want to return per request, the default is 100 and the maximum limit is 10000.

Paginating Results - page()

If your data set is too large, you can paginate the results using the "page" parameter. Here's an example:

Replace "2" with the number corresponding to the page number of results you wish to retrieve. The default page number is 1.

Apply filters - EQ (Equal to)

To narrow down your results based on certain matching criteria, you can use the "eq" filter. Here's an example to retrieve a user with a specific username:

Replace "Username" with the actual username you wish to search.

Apply filters - lt(Less than)

The "lt" filter allows you to limit your search results based on values less than a specified number. This is commonly used for filtering results based on numerical values. Here's an example to retrieve users with an age less than a specific number:

Replace "Age" with the actual numeric age you wish to use as your upper limit in the search.

Apply filters - gt(Greater than)

To filter your results based on values greater than a certain threshold, you can use the "gt" filter. Here's an example to retrieve users whose names in ascending order surpass a specific username:

Replace "Username" with the actual username that is to be the starting point of your search.

Apply filters - le(Less than or equal to)

To filter your results based on certain criteria lower than or equal to a set parameter, you can use the "le" filter. Here's an example to retrieve a user with a name that falls prior or at the same position in the alphabet as a specified name:

Replace "Username" with the actual name elements you wish to set as the cut-off.

Apply filters - ge(Greater than or equal to)

To filter results based on a value that is greater than or equal to a specific figure, use the "ge" filter. For instance, here's how you can retrieve users with a certain minimum age:

Replace "Age" with the desired minimum age.

Apply filters - ne(Not Equal to)

To retrieve results that do not match a specific criterion, you can use the "ne" filter. Below is an example on retrieving all the users with usernames not matching a specified one:

Replace "Username" with the actual username you wish to exclude from the search results.

Apply filters - nin(Not in)

To exclude certain results from your query, you can use the "nin" filter. Here's an example to retrieve users not having a specific username:

Replace "Username" with the actual username you wish to exclude in your search.

Apply filters - in(In list)

To access data for multiple values in a single field, you can use the "in" parameter. Here's an example to retrieve users with specific names:

Replace 'Name1' and 'Name2' with the actual names you wish to search.

Apply filters - contains(Like)

To fetch your results based on a specific sequence of characters within a string, you can use the "contains" filter. Here's an example to retrieve a user with a username containing specific characters:

Replace "ha" with the actual sequence of characters you wish to search within usernames.

Apply filters - sw(Starts with)

The "sw" filter allows you to modify your results so that you only see entries that begin with a certain string. Here's an example of how to find a user whose username begins with a specific string:

Swap "Username" with the string you're wanting to search for.

Apply filters - ew(Ends With)

To narrow down your results based on a certain ending criteria, you can use the "ew" filter. Here's an example to retrieve a user whose username ends with a specific set of characters:

Replace "Username" with the specific end sequence you want to search for in the usernames.

Include Single Related Object

You can include related objects in your resource responses by using the "include" query parameter. Here's an example:

Note: Replace "group" with the actual related object.

Include Multiple Related Objects

If you need to include more than one related object, separate them with commas. Here's an example:

Note: Replace "group", "role" with the actual related objects.

Include Nested Related Objects

In some cases, you might want to include nested related objects. Use a dot to indicate the hierarchy. Here's an example:

Note: Replace "user", "group" with the actual related objects.

Step 1: Locate your Instance name

Your instance name should have been provided to you when your MasterSales account was setup. If you are unable to locate your instance name, please contact MasterSales support.

Step 2: Identify the Business Object

A business object is a type of resource you need to access in your MasterSales system. It can be anything ranging from sales leads to reports. You should know the name of the business object that you need to access.

Step 3: Construct the URL

Using your instance name and the business object, construct a URL using the following pattern:

Replace {version} with the actual version and {InstanceName} with your actual instance name and {BO} with the business object you wish to access.

Step 1: Understand the URL Pattern

The URL pattern to access a single resource is as follows: https://api.mastersales.com/v1/{InstanceName}/{BO}/{ResourceID} Where:

• {InstanceName} is the name of your MasterSales instance.
• {BO} is the name of the business object you want to access.
• {ResourceID} is the ID of the resource you want to access.

Step 2: Insert the Instance Name

Enter the name of your MasterSales instance in place of {InstanceName} in the URL.

Step 3: Insert the Business Object Name

Enter the name of the business object you wish to access in place of {BO} in the URL.

Step 4: Insert the Resource ID

Enter the ID of the resource you wish to access in place of {ResourceID} in the URL.

This is a simple guide that you can follow to successfully access any resource in the MasterSales system.

Understanding the Response

In the response, the "links" section is the HATEOAS implementation. Each link consists of a "rel" attribute, denoting the relationship between the current resource and the linked resource. The client application can utilise these links to navigate through the available resources and actions in the API.

Decoupling Client Application and API Implementation

Overall, HATEOAS aims to decouple the client application from the API implementation. It does so by allowing the API to evolve independently while providing a uniform method for navigating the array of resources and actions.

Sample HATEOAS Links

{
    "href": "https://api.mastersales.com/v1/inst/Account?page=1&rows=1",
    "rel": "First page"
},
{
    "href": "https://api.mastersales.com/v1/inst/Account?page=1&rows=1",
    "rel": "Previous page"
},
{
    "href": "https://api.mastersales.com/v1/inst/Account?page=2&rows=1",
    "rel": "Next page"
},
{
    "href": "https://api.mastersales.com/v1/inst/Account?page=9&rows=1",
    "rel": "Last page"
},
{
    "href": "https://api.mastersales.com/v1/inst/Account?page=@page&rows=1",
    "rel": "page(n)"
}
                    

In the HATEOAS example above, various links are provided to navigate to the first page, previous page, next page, last page, and a specific "n-th" page. This example demonstrates how a client application can utilize these links to effectively navigate through the API's resources.