API best practices

Best practice recommendations are based on the experience of IBM customers, service representatives, and quality assurance testers. These best practices intent is to provide general guidance in areas of concern that have arisen when using the software.

To make API calls, you must use a valid access token. A token is typically valid for 12 hours. Generate the token once and reuse it by caching the token. As an example, you may store the token in memory on the client side and reuse it for all the subsequent calls that are made from the same client. For more information about generating a token, see Accessing and Authenticating APIs.
If an API is called with a missing or an invalid token, an authenticate error is received in the response. As a best practice to handle authentication errors, issue a fresh token generation request to refresh the token cache. Then, retry by calling the Sterling Intelligent Promising API with the renewed token.
Implement a method to automatically regenerate a token before the expiration time (for example, every 11 hours) or when you encounter a 401 Unauthorized response.
Ensure that the maximum payload size per request does not exceed 500 KB. This limit is set to maintain stability and to avoid failures.
For best performance, limit each API call to 100 item-node or item-network combinations. Then, separate any additional combinations into multiple API calls.
Pass HTTP headers that are only mentioned in the API documentation. For more information, see API documentation.

Availability API

For product details or list pages on a website, use the Get Node Availability Product by Date API (/availability/{itemId}/node) or Get Network Availability Product by Date API (/availability/{itemId}/network) for the item in question.
For carts or orders, use the Get Node Availability API (/availability/node) or Get Network Availability API (/availability/network) with the items in the cart or order.
For cart check-out, use the Reservations API (/reservations) to prevent over-selling.
For the V2 availability APIs, use date format for requestedEndTs. For example, "2020-03-02Z".
If a timestamp is used instead of a date, such as 2020-03-02T15:43:18.279Z with a time component, then the API issues a bad request exception.
Note: The date format validation for requestedEndTs is applicable from the end of the July release.

Distribution group API

The Update Distribution Group API supports only the PUT method. As the PUT request is idempotent, updating an existing distribution group replaces the entire group.
- If you are adding new ship nodes to an existing distribution group, ensure that the payload also includes existing ship nodes.
- If you are deleting ship nodes from an existing distribution group, ensure that the payload includes only the ship nodes that you want to keep in the group.
The API automatically synchronizes the availability of the distribution group when ship nodes are added or removed from the group.
Do not trigger subsequent syncs for the same distribution group until the previous syncs are complete. Distribution Group Sync is not an instant process. Also, it is recommended to submit fewer requests. For example, if you are removing three nodes from the distribution group, submit one request with all three nodes removed.
You can retrieve the sync status with the GET Job API. When the Distribution Group API is called, a reference to a URL for the GET Job API is presented in the API output. For example,
```
{
    "job": {
        "href": "http://api.watsoncommerce.ibm.com/inventory/us-abcdabcd/v1/jobs/a2f173e7-2023-4e3d-b21d-2b6801f61d1b"
    }
}
```
You can call the GET Job API with this URL to get the state of the provided job, as shown in the following example.
```
{
    "id": "a2f173e7-2023-4e3d-b21d-2b6801f61d1b",
    "status": "completed",
    "triggeredTs": "2021-02-22T19:59:12.585Z",
    "startedTs": "2021-02-22T19:59:12.849Z",
    "completedTs": "2021-02-22T19:59:13.155Z",
    "data": {
        "distributionGroupId": "USEast",
        "diffNodes": [
            "USEast-Node1",
            "USEast-Node2"
        ],
        "sourceTs": "2021-02-22T19:59:12.565Z"
    }
}
```
Review the status field of the output.

completed

The job completed successfully. In this case, you can submit the next request.

started

The job is in progress. In this case, do not trigger another synchronization for the same distribution group. However, you can trigger a synchronization for a different distribution group.

triggered

The job did not start yet. In this case, do not trigger another synchronization for the same distribution group. However, you can trigger a synchronization for a different distribution group.

If the API returns a status code of 404, you can safely resubmit the request.