Getting started
This guide will guide you through the basics of the usage of our API. By the end of reading through this guide you will be equipped by the knowledge of how to implement API requests to any of your endpoints.
Recommended tools
For development purposes we recommend any tool that supports GraphQL exploration, here are a few of them:
Environments in Eneba API
Eneba API provides two environments: sandbox
and production
.
We highly recommend testing your API integration in the sandbox
environment first.
This is a safe way to avoid unintentional purchases, charges, or lost keys.
The difference between the two of them is the base URL and credentials used. Please use the following base URL while making HTTP requests:
https://api-sandbox.eneba.com/graphql/
Regarding credentials, reference the next section.
Getting Access
Eneba API uses OAuth 2.0 authorization mechanism with Bearer
tokens.
If you are not familiar with OAuth, please read more on
OAuth Access Tokens
and Refreshing OAuth Access Tokens.
1. Getting the credentials
You can get your credentials from the Eneba dashboard.
2. Authentication
After you have generated the sandbox or production credentials, you need to get an access_token
.
To get it, you will have to use the Auth ID
and Auth Secret
values you got in the "Getting the credentials" step above.
The following describes how you can get an access token for sandbox
or production
environments.
Request parameters:
Field | Value |
---|---|
url | https://api-sandbox.eneba.com/oauth/token |
method | POST |
Content-Type | application/x-www-form-urlencoded |
Request body:
Field | Value |
---|---|
client_id | 917611c2-70a5-11e9-00c4-ee691bb8bfaa |
grant_type | api_consumer |
id | Auth ID value from the Eneba dashboard |
secret | Auth Secret value from the Eneba dashboard |
Example request:
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=api_consumer&client_id=917611c2-70a5-11e9-00c4-ee691bb8bfaa&id={Auth-ID}&secret={Auth-Secret}" \
https://api-sandbox.eneba.com/oauth/token
Example response:
{
"token_type": "Bearer",
"expires_in": 216000,
"access_token": "eyJXAiNiJ9.eyJhdWOYS5jb20ifQ.KOQQxuzLY",
"refresh_token": "44c6d767755aeb3851908a2f1d"
}
Note that the authentication response on sandbox
does not have the refresh_token
.
3. Using the access token
All requests to our GraphQL API must contain a Bearer
access token in the Authorization
HTTP header. Use the access_token
you acquired in step #2 as follows:
Authorization: Bearer <access_token>
The acquired access_token
is temporary and will expire after the expires_in
time passes. You will need to implement the
OAuth token refresh flow
in order to keep the API implementation secure.
It is not recommended to run Authentication before every request. This may result in rate-limiting rules applied to your entire IP. The following section describes rate limiting in more detail.
Rate limiting
To protect internal systems, Eneba API implements rate-limiting.
There are two types of rate-limiting strategies - global
and action
.
Global limits
Your IP address is limited to 5000 requests per 10 min
.
Solution to global limits
Eneba uses GraphQL for its API this allows to batch multiple GraphQL requests into a single HTTP request.
Example:
We need to update the price of all our auctions
.
Classical approach
In a classical API we would have to perform two HTTP requests and update the price one-by-one:
mutation {
S_updateAuction(
input: {
id: "0c000bd0-5109-147a-ac7f-ca90e75ca652"
price: { amount: 1100 currency: "EUR" }
}
) {
isSuccessful actionId
}
}
mutation {
S_updateAuction(
input: {
id: "26d8a2a1-5dee-147a-ac7f-ca88a25ca05f"
price: { amount: 199 currency: "EUR" }
}
) {
isSuccessful actionId
}
}
Batched GraphQL approach
Now, if we would use batched requests feature, we could send a single HTTP request:
mutation updateAuction_1 {
S_updateAuction(
input: {
id: "0c000bd0-5109-147a-ac7f-ca90e75ca652"
price: { amount: 1100 currency: "EUR" }
}
) {
isSuccessful actionId
}
}
mutation updateAuction_2 {
S_updateAuction(
input: {
id: "26d8a2a1-5dee-147a-ac7f-ca88a25ca05f"
price: { amount: 199 currency: "EUR" }
}
) {
isSuccessful actionId
}
}
What we added here is the names for individual GraphQL requests.
You can read more about batched requests in Apollo Graphql docs.
Action limits
Some actions are protected by specific limits:
Action | Rate limit |
---|---|
S_updateAuction | 1 request per 3 sec. |
B_balance | 2 requests per 1 min. |
C_announcements | 2 requests per 1 min. |
Solution to action limits
Make all changes in a single GraphQL request.
Example:
We need to enable particular auction and update its price.
Instead of making two separate requests to enable the auction and to update its price, we can use a single GraphQL request and make such modifications in one go:
mutation {
S_updateAuction(
input: {
id: "26d8a2a1-5dee-147a-ac7f-ca88a25ca05f"
price: { amount: 199 currency: "EUR" }
enabled: true
}
) {
isSuccessful actionId
}
}