Overview
Introduction
The Gelato Connect API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.
Usage of these environments is dependent on having a valid API key. Please refer to the section Authentication on how to obtain such a key. Please use the urls below to connect to either the test or live environment.
| Environment | URL |
|---|---|
| test | https://connect.test.gelato.tech/ |
| live | https://connect.live.gelato.tech/ |
If you have any questions or need help please use our contact page.
Authentication
All our Gelato Connect API calls will require you to have a valid API token or API-KEY and provide it in the header of each call. Please note that we require you to use different keys for testing and live environment. All communication is done through HTTPS and calls made over plain HTTP will fail.
Authenticate using API key:
- Please contact Gelato team through the contact page to register and receive API key
- Once you have a key you would send that using the
X-API-KEYheader.
Authenticate using Token (deprecated):
- Please contact Gelato team through the contact page to register and receive API access token
- Once you have a token you would send that using the Authorization: Bearer token header.
- Note: This type of authorization should be used only in
/v1/version of API endpoints
Rate limits
Rate limits are restrictions that our API imposes on the number of times a user or client can access our services within a specified period of time. All of these requests count towards your personal rate limit of 100 requests per second.
Why do we have rate limits?
Rate limits are a common practice for APIs, and they're put in place for a few different reasons:
- They help protect against abuse or misuse of the API. For example, a malicious actor could flood the API with requests in an attempt to overload it or cause disruptions in service. By setting rate limits, Gelato can prevent this kind of activity.
- Rate limits help ensure that everyone has fair access to the API. If one person or organization makes an excessive number of requests, it could bog down the API for everyone else. By throttling the number of requests that a single user can make, Gelato ensures that the most number of people have an opportunity to use the API without experiencing slowdowns.
- Rate limits can help Gelato manage the aggregate load on its infrastructure. If requests to the API increase dramatically, it could tax the servers and cause performance issues. By setting rate limits, Gelato can help maintain a smooth and consistent experience for all users.
Retry logic
If an API rate limit is exceeded, you will often receive a 429 status code. To avoid impact to your workloads, you should proactively implement retry techniques. The following techniques increase the reliability of your application.
- Retry: It is a strategy designed to handle situations where HTTP requests might fail due to intermittent issues or temporary connectivity problems. This mechanism ensures that failed requests are automatically reattempted, thereby increasing the likelihood of a successful outcome. The retries can be executed immediately, or they can be spaced out over time for more persistent issues. Every API call should implement retry, in the application code where API calls are made.
- Exponential backoff: The idea behind exponential backoff is to use progressively longer waits between retries for consecutive error responses. Exponential backoff can lead to very long backoff times, because exponential functions grow quickly. You should implement a maximum delay interval and a maximum number of retries. The maximum delay interval and maximum number of retries are not necessarily fixed values. They should be set based on the operation being performed and other local factors, including network latency.
- Jitter: Retries can be ineffective if all clients retry at the same time. To avoid this problem, we employ jitter, a random amount of time before making or retrying a request to help prevent large bursts by spreading out the arrival rate. Most exponential backoff algorithms use jitter to prevent successive collisions.
For more information, including examples, see:
- Exponential backoff and jitter blog post
- Examples of backoff and jitter using Python
Errors
The Gelato API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
- Codes in the 2xx range indicate success.
- Codes in the 4xx range indicate a structural or data error in the request (e.g., a required parameter was omitted, referenced order was not found, etc.).
- Codes in the 5xx range indicate an error with Gelato's API servers (these are rare).
Webhooks
The Gelato Connect API will send webhook calls to notify your application about a new order or if changes needed on a previous submitted order. The Gelato Connect API sends the calls via an HTTP POST request, to specific endpoint URLs that you have provided to us.
Webhook Authentication
The webhooks that are configured must also follow a secure path. How do we maintain integrity between our partners? Below is the outline:
- The Gelato team will prepare an JWT Token that we will use as the bearer.
- Gelato Connect API will send this token using the Authorization: Bearer token header.
- The partner will validate the JWT Token signature using public key provided by ISS URL
Gelato ISS addresses:
Example of token verification in PHP language:
Make sure you have phpseclib installed. It can be done via Composer
composer require phpseclib/phpseclib:~2.0
<?php
include 'vendor/autoload.php';
function validate($token): bool
{
$part = explode('.', $token);
# Split token
$header = $part[0];
$data = $part[1];
$signature = $part[2];
# Define hashtype
$headerObj = jsonUrlDecode($header);
$hashtype = str_replace('RS', 'sha', $headerObj->alg); // sha256
$dataObj = jsonUrlDecode($data);
# Verify issuer URL belongs to Gelato
$gelatoISSURLs = [
'https://auth.ie.test.gelato.tech/auth/realms/gelato-api', // test env
'https://auth.ie.test.gelato.tech/auth/realms/gelato-connect-api', // test env
'https://auth.gelato.com/auth/realms/gelato-api', // live env
'https://auth.gelato.com/auth/realms/gelato-connect-api', // live env
];
if (!in_array($dataObj->iss, $gelatoISSURLs)) {
return false;
}
# Get public key using issuer URL
$issuerContent = file_get_contents($dataObj->iss);
$issuerContentObj = json_decode($issuerContent);
$publicKey = $issuerContentObj->public_key;
# Define payload
$payload = $header . '.' . $data;
# Decode signature
$signature = base64UrlDecode($signature);
# Verify token signature
$rsa = new \phpseclib\Crypt\RSA();
$rsa->setHash($hashtype);
$rsa->loadKey($publicKey, \phpseclib\Crypt\RSA::PUBLIC_FORMAT_PKCS1);
$rsa->signatureMode = \phpseclib\Crypt\RSA::SIGNATURE_PKCS1;
if ($rsa->verify($payload, $signature)) {
return true;
}
return false;
}
function base64UrlDecode($base64url)
{
$padding = strlen($base64url) % 4;
if ($padding > 0) {
$base64url .= str_repeat("=", 4 - $padding);
}
$str = strtr($base64url, '-_', '+/');
return base64_decode($str);
}
function jsonUrlDecode($str)
{
$data = base64UrlDecode($str);
return json_decode($data);
}
$token = '<<<GELATO TOKEN FROM HEADER>>>';
validate($token);
Webhook URL
Your Webhook URL endpoints must be RESTful. All calls must be implemented as HTTP post and with TLS encrypted. The HTTP response code 2xx is expected on positive calls, all other response codes will be considered as error.
Request data
All events will be posted as JSON objects to your Webhook URL endpoint. The documentation for each webhook request is described below.
Response data
No response content is expected, any content will be ignored.
Retries
Webhooks will try to send the request data 3 times, with 5 seconds delay between each try, if an HTTP status 2xx is not returned.