Best practices

To ensure a robust API integration, we encourage you to code your client defensively and respecting below best practices.

We enforce the usage of an explicit API version and respect semantic versioning to avoid breaking changes. This guarantees you that your client will continue to work when we add new features in our API.

Non-breaking changes are added regularly and your client must be prepared to receive unknown fields or response code and ignore new features.

Please follow these recommandations when implementing your API client:

• Parse the API response as a JSON object and dot not rely on regular expressions or other means to manually parse it.
• Ignore unknown fields/headers in responses.
• Be prepared to handle unknown HTTP status codes, consider them as extensibles.
• Be prepared to receive unknown values in enumerations, consider them as extensibles.
• Follow the redirect when the server returns HTTP status code 301 (Moved Permanently). Every redirect response sets the Location header with the new URI to go to. If you receive a redirect, it's best to update your code to follow the new URI, in case you're requesting a deprecated path that we might remove.

In addition, the following recommandations can make your client more robust:

• Implement a "Retry with exponential backoff" coding pattern for your REST API call logic. This means if your request fails due to a rate limit or a server-side error, your client would automatically recover and try again after some time.
• Don't manually parse URLs contained in the API response. For example, paginated endpoints return pagination links with an opaque cursor. You shouldn't try to parse this data or try to guess and construct the format of future URLs. Your app is liable to break if we decide to change the URL.
• Don't abuse lacks of constraints in API specification, like sending several MB of data in a string. A constraint can be defined any time without notice.