Как работать с API

Для работы с запросами необходимо авторизоваться на платформе публичных API TravelLine — Partner API.

Процесс авторизации

Авторизация происходит через OAuth2.0.

OAuth 2.0 – это стандарт авторизации, который позволяет приложениям получать доступ к данным.

Для работы с API в запросах необходимо передавать ключ доступа JSON Web Token (JWT).

JWT (JSON Web Token) — это специальный формат токена, который позволяет безопасно передавать данные между клиентом и сервером.

Получение JWT происходит через Client credentials flow, то есть авторизацию по секретному ключу доступа.

Для запроса ключа доступа необходимы параметры: Client ID и Client Secret.

Диаграмма взаимодействия

TravelLine. Auth Server: https://partner.tlintegration.com/auth/token

TravelLine. Content API: https://partner.tlintegration.com/api/content/

Access Token

Лимиты на авторизацию: 3 в секунду, 15 в минуту, 300 в час по одному IP-адресу.

Время жизни токена: 15 минут.

Endpoint авторизации: PROD — https://partner.tlintegration.com/auth/token

Пример Access Token:

На сайте JWT.IO можно расшифровать Access Token.

Пример расшифрованного токена:

PAYLOAD:

{
"exp": 1698916036,
"iat": 1698915136,
"jti": "a2cdba0d-c407-49df-8b4d-92a5355d1a1f",
"iss": "https://partner.tlintegration.com/auth/realms/PartnerApi",
"aud": "TravelLine.PartnerAPI",
"sub": "86a4b6be-0a74-4cb9-b3ab-b462ee0bb2bd",
"typ": "Bearer",
"azp": "pa3",
"scope": "",
"api_accesses": [
"content"
]
}

Обратите внимание. Refresh token не используется.

Best practices

1. Кешировать на стороне клиента Access Token и использовать его повторно в своих запросах.

2. Использовать библиотеки для OAuth2.0:

.net

https://identitymodel.readthedocs.io/en/latest/client/overview.html
Microsoft.Extensions.DependencyInjection

js

https://www.npmjs.com/package/oidc-client?activeTab=readme
https://github.com/IdentityModel/oidc-client-js/wiki

php

https://github.com/jumbojett/OpenID-Connect-PHP

curl

curl -L -X POST "https://partner.tlintegration.com/auth/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=XXXXXXXXXXXX" -d "client_secret=XXXXXXXXXXXX"

Как сделать запрос к API в Swagger

Swagger — это инструмент, который позволяет автоматически описывать API на основе его кода.

Спецификация и примеры доступны в Swagger.

Чтобы сделать запрос:

1. Выберите нужное API из выпадающего списка.

2. Авторизуйтесь с помощью Client ID и Client Secret.

3. Если вы переключаетесь между API, заново авторизуйтесь.

Работа с API происходит с помощью отправки GET или POST запросов.

При некорректных запросах или проблемах в работе API, возвращается информация об ошибках.

Как авторизоваться в Swagger

1. Нажмите Authorize.

2. Введите параметры Client ID и Client Secret, нажмите Authorize.

3. Затем нажмите Close.

Как сделать запрос к API в Swagger

Описанная ниже последовательность действий применяется для выполнения запроса любого из методов в описании API.

1. Выберите API:

• Content API — описание и фотографии средств размещений, категорий номеров, тарифов и услуг;

• Reservation API — информация о бронированиях средств размещений;

2. Выберите запрос, который доступен в выбранном API. Например, «Получить информацию о средствах размещения»:

3. Нажмите Try it out:

4. Введите свои данные:

5. Нажмите Execute:

Важно: перед тем, как выполнить запрос, обратите внимание на описание параметров.

Если запрос успешно выполнен, в ответ вы получите «Код 200» и детальное описание средств размещений.

Если произошла ошибка, вы получите код ошибки и ее описание. Например:

• «Код 400» — неверный запрос.

Может произойти, если вы отправили неверные данные.

В этом примере было превышено допустимое число элементов, которое было введено в поле count.

• «Код 401» — ошибка авторизации.

Может произойти, если вы отправили неверные данные авторизации.

Аналогично выполняются и все остальные запросы к API.

Чтобы просмотреть в методе все входящие и исходящие параметры, их типы и описание, нажмите на Schema.