Appearance
Using the Printlane API
Implementation
Please follow these practices when implementing the Printlane 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 easily exploited;
- The amount of API calls should be limited to a reasonable amount to prevent rate limiting (see Rate Limiting);
- Errors returned from the Printlane 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 Printlane API impacting these flows. For example: pushing order data to Printlane 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 Printlane Support for assistance about how to implement your specific use-case.
Authentication
For every request to the API, you need to send 3 custom HTTP headers:
| Header | Description |
|---|---|
X-Printlane-Store | The ID of your store (displayed in the Settings page of Printlane Studio). |
X-Printlane-Api-Key | Your API key. |
X-Printlane-Api-Signature | 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-Printlane-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.
WARNING
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.
Generating API signatures
Each API endpoint requires generating a header X-Printlane-Api-Signature. This signature is a string generated using:
Example
The endpoint requires following verification string Store ID + Template ID. The Store ID is equal to 634fc08da68c799b9429571e and the Template ID is equal to 634fc09e4325a84d4f03f4fe
- resulting verification string:
634fc08da68c799b9429571e634fc09e4325a84d4f03f4fe
You need to compute a sha256 HMAC signature with the verification string and your API secret in code, or using an online generator like https://www.freeformatter.com/hmac-generator.html.
If your API secret is a084db82-f995-44cd-98ff-837be3c9af3f, this will result in following HMAC: a05b369fcd333d475e2b7af117023acc8b54b75f534250f0a2b4deb27c637c2d.
You need this value for the X-Printlane-Api-Signature header when sending requests to the API.
You can find your Store ID on the settings page in Printlane Studio.
Rate limiting
The Printlane API applies rate limiting to all endpoints following the leaky bucket algorithm.
Exceeding rate limits
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
How quota's are communicated
Each call to the API returns following response headers:
| Response header name | Example value | Description |
|---|---|---|
ratelimit-limit | 30 | You are allowed to execute 30 API requests in 1 minute |
ratelimit-remaining | 17 | You have 17 requests remaining in the current window |
ratelimit-reset | 24 | The remaining time in the current window in seconds |
Requests will succeed again after enough requests have emptied out within the current window.