API Implementation Considerations

Please be aware of these considerations when building or integrating applications with the RetailNext API.

We work to keep the API interface stable, but our API contract is limited to the documented query request and response documentation. Other aspects of the API service, like the required security configuration, certificate issuer, and HTTP protocol may change at any time, but these changes should not cause problems for clients that follow web standards.

Ongoing Security Updates

To maintain effective security, RetailNext will periodically revise the encryption protocol version and cipher suite requirements for our API services. Currently, a minimum version of TLS 1.2 is required. While we will do our best to provide advance notice of these changes, we may make emergency changes in response to reported security vulnerabilities.

We may also change update the security certificate used by the service at any time prior to its expiration, and we may use a different certificate authority (CA). The CA will always be one trusted by mainstream operating systems and web browsers.

Versions & Compatibility

For a given version of an API method, we try to maintain backwards compatibility with existing invocations of the method. However, the responses to queries will change as we add product features, and an effective integration should ignore unexpected data. For example, if we add a new property to a store location (like an occupancy limit), that information may be added to API responses that return information about locations.

HTTP Headers

API clients should adhere to web standards.

HTTP headers must be treated as case-insensitive strings. We may change the case of existing HTTP headers without notice, and we may introduce new headers in responses.

For example, a recent change caused the X-Page-Next header to be changed to x-page-next.

Retry on Errors

Sometimes, an API request may time out or return an error code, whether that is due to a factor under RetailNext’s control or not. API clients should detect errors and retry requests as appropriate, especially for HTTP 502 or other 5xx errors.

Batch /datamine Requests

When requesting data for multiple stores, it is more efficient to request data for batches of 100-200 stores instead of making one request per store.