API Reference

Both REST and GraphQL can be used to call the Oxilor Data API methods.

If you are using GraphQL, you can stitch your schema with the Oxilor Data API schema using the @graphql-tools/stitch library. In this case, all methods available in the Oxilor Data API will be added to your API.

Endpoints:

• REST – https://data-api.oxilor.com/rest
• GraphQL – https://data-api.oxilor.com/graphql

Authentication

The Oxilor Data API uses API keys to authenticate requests, so you should first get your API key. If you want to use the Oxilor Data API in multiple projects, we recommend creating a separate API key for each project. All API requests without authentication will fail.

Get an API key

Keep your API keys in secure! Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth.

There are 2 ways to authenticate requests:

1. Specify the Authorization header: Authorization: Bearer YOUR_API_KEY
2. Specify the key query parameter: /rest/regions?key=YOUR_API_KEY

If you specify both the Authorization header and the key query parameter, the API will take the key from the parameter.

Language

The database contains the names of regions in dozens of different languages: English, German, French, Polish, Dutch, Russian, Spanish, Italian, Chinese, Portuguese, etc.

There are 2 ways to specify the language in which you want to get the names of the regions:

1. Specify the accept language header: Accept-Language: ru
2. Specify the lng query parameter: /rest/regions?lng=ru

The language code must be specified in accordance with the ISO-639-1 standard. By default, English is used.

Pagination

Some API methods return an array of objects. These methods share a common structure that conforms to the GraphQL Cursor Connections Specification. The Oxilor Data API supports both forward and backward pagination.

The response has the following structure:

{
  "edges": [
    {
      "node": {},
      "cursor": "Y29ubjo1"
    },
    {
      "node": {},
      "cursor": "Y29ubjoxMA"
    },
    {
      "node": {},
      "cursor": "Y29ubjoxMg"
    },
    {
      "node": {},
      "cursor": "Y29ubjoxMw"
    },
    {
      "node": {},
      "cursor": "Y29ubjoxNQ"
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "hasPreviousPage": false,
    "startCursor": "Y29ubjo1",
    "endCursor": "Y29ubjoxNQ"
  }
}

An array of objects is stored in the edges node. Each object is stored in the node. In order not to complicate the example, empty objects are stored in these nodes. Each object has a cursor that is used to get the next or previous page.

The pageInfo contains information about the current page. When the forward pagination is used, the hasNextPage flag indicates whether the list items exist on the next page, and the hasPreviousPage flag is always false. In contrast, when the backward pagination is used, the hasPreviousPage flag indicates whether the list items exist on the previous page, and the hasNextPage flag is always false.

The startCursor and endCursor contain the cursor of the first and last list item on the current page, respectively.

Forward pagination

The forward pagination is used to get the list items from the beginning to the end. The number of elements on the page is specified in the first parameter. To get the next page, you must also pass the cursor of the last received element in the after parameter. By default, the value of first is 20.

Example of a REST request to get the first 10 items:

curl -X GET 'https://data-api.oxilor.com/rest/regions?first=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example of a REST request to get the next 10 items:

curl -X GET 'https://data-api.oxilor.com/rest/regions?first=10&after=Y29ubjoyNg' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Backward pagination

The backward pagination is used to get the list items from the end to the beginning. This type of pagination uses the last and before parameters instead of first and after.

Example of a REST request to get the last 10 items:

curl -X GET 'https://data-api.oxilor.com/rest/regions?last=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example of a REST request to get the next last 10 items:

curl -X GET 'https://data-api.oxilor.com/rest/regions?last=10&before=Y29ubjoxMjM4MjIwMA' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Method list