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. You must 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 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 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.
  • The maximum payload that can be sent is 500 KB. However, IBM recommends no more than 100 items per payload. If you need to send more than 100 item node, invoke multiple API calls.
  • You must only pass HTTP headers that are mentioned in the API documentation. For more information, see API documentation.

Availability API

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.