Справочник по API

Для вызова методов Oxilor Data API можно использовать как REST, так и GraphQL.

Если вы используете GraphQL, то вы можете объеденить вашу схему со схемой Oxilor Data API, используя библиотеку @graphql-tools/stitch. В этом случае, все методы, доступные в Oxilor Data API, будут добавлены в ваш API.

Базовые URL:

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

Аутентификация

Oxilor Data API использует API-ключи для аутентификации запросов, поэтому в начале вам нужно получить свой API-ключ. Если вы хотите использовать Oxilor Data API в нескольких проектах, то мы рекомендуем создавать отдельный API-ключ для каждого проекта. Все API-запросы без аутентификации завершатся ошибкой.

Получить API-ключ

Храните свои ключи в безопасности! Не публикуйте их в общедоступных местах, таких как GitHub, код на стороне клиента и т.д.

Существует 2 способа аутентификации запросов:

1. Указать заголовок Authorization: Authorization: Bearer YOUR_API_KEY
2. Указать параметр key: /rest/regions?key=YOUR_API_KEY

Если вы укажите как заголовок Authorization, так и параметр key, то API возьмет ключ из параметра.

Язык

База содержит названия регионов на десятках различных языков: английский, немецкий, французский, польский, голландский, русский, испанский, итальянский, китайский, португальский и др.

Существует 2 способа указать язык, на котором вы хотите получить названия регионов:

1. Указать заголовок Accept-Language: Accept-Language: ru
2. Указать параметр lng: /rest/regions?lng=ru

Код языка должен быть указан в соответствии со стандартом ISO-639-1. По умолчанию используется английский язык.

Пагинация

Некоторые API-методы возвращают массив объектов. Эти методы имеют общую структуру, которая соответствует спецификации GraphQL Cursor Connections. Oxilor Data API поддерживает пагинацию как вперед, так и назад.

Ответ имеет следующую структуру:

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

Массив объектов хранится в узле edges. Каждый объект хранится в node. Чтобы не усложнять пример, в этих узлах хранятся пустые объекты. Каждый объект имеет курсор, который используется для получения следующей или предыдущей страницы.

pageInfo содержит информацию о текущей странице. Когда используется пагинация вперед, флаг hasNextPage показывает, существуют ли элементы списка на следующей странице, а флаг hasPreviousPage всегда false. Напротив, когда используется навигация назад, флаг hasPreviousPage указывает, существуют ли элементы списка на предыдущей странице, а флаг hasNextPage всегда false.

startCursor и endCursor содержат курсор первого и последнего элемента списка на текущей странице соответственно.

Пагинация вперед

Пагинация вперед используется, чтобы получать элементы списка от начала до конца. Количество элементов на странице задается параметром first. Чтобы получить следующую страницу, вы должны также передать курсор последнего полученного элемента в параметре after. По умолчанию значение first равно 20.

Пример REST-запроса для получения первых 10 элементов:

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

Пример REST-запроса для получения следующих 10 элементов:

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

Пагинация назад

Пагинация назад используется, чтобы получать элементы списка с конца к началу. Этот тип пагинации использует параметры last и before вместо first и after.

Пример REST-запроса для получения последних 10 элементов:

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

Пример REST-запроса для получения следующих последних 10 элементов:

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

Список методов