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:

• Insomnia
• Altair
• Postman

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:

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 your credentials

You can get your credentials from the credentials section of Eneba dashboard.

To get credentials for production, add one or more IP addresses (max 25) to the allowlist.

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.

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>

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.

We have a hard limit on 750 operations per batch query and 500 per batch mutation. These limits will most likely be reduced to 200 in the future.

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.

GraphQL batched requests limits

When you batch several GraphQL operation in a single request avoid surpassing 100 queries or mutations for better performance. Going over this, might result in getting blocked.

Action limits

Some actions are protected by specific limits:

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
  }
}