Using the Colorlab API
Please follow these practices when implementing the Colorlab API:
- All API calls should be implemented on the server side for security purposes;
- API calls should never be triggered from the client side (for example with an AJAX call from the browser), as such implementations can be easilly exploited;
- The amount of API calls should be limited to a reasonable amount to prevent rate limiting (see Rate Limiting);
- Errors returned from the Colorlab API should be handled gracefully by your application;
- API calls should be implemented apart from existing flows in which your end users are involved.
This will prevent errors or downtime of the Colorlab API impacting these flows. For example: pushing order data to Colorlab should happen after orders are placed, preferably in a spreaded way (e.g. using a cron-job) to prevent Rate Limiting when a lot of orders are placed at the same time.
As ignoring these practices could result in disabling your API keys, please feel free to contact Colorlab Support for assistance about how to implement your specific use-case.
For every request to the API, you need to send 3 custom HTTP headers:
||The shop ID of your shop (displayed in the
||Your API key.|
||The signature generated on your side using an API secret. The signature is used to validate your request.|
Every time you request an API endpoint, you need to send along a signature using the
X-Colorlab-Api-Signature header. This signature guarantees that the request is valid and not accessible by other parties.
The signature is calculated on a per-endpoint basis. Every calculation involves your API secret.
Important: never send your API secret to the endpoint, only use it to generate the signature. This makes sure requests can only originate from the source which knows the API secret.
The Colorlab API applies rate limiting to all endpoints following the leaky bucket algorithm.
You can make a maximum number of requests per minute. Each request counts equally, regardless
of how much or how little data is returned. All requests that are made after rate limits have been
exceeded are throttled and an
HTTP 429 Too Many Requests error is returned.
When implementing the API, you should take into account that limits apply, and prevent exceeding these limits by:
- limiting the amount of requests at a time
- add error handling that allows you to catch these errors if they do occur
Requests will succeed again after enough requests have emptied out within the timeframe.
For more information about the amount of requests and timeframes that apply to each endpoint, please contact Colorlab Support.