Как работать с 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:

eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI2OGZjOHRNUGFSUHRyRHYtVHV2WEpncUNGTE1CVGRheTBpQkdJSUE3amxvIn0.eyJleHAiOjE2OTg5MTYwMzYsImlhdCI6MTY5ODkxNTEzNiwianRpIjoiYTJjZGJhMGQtYzQwNy00OWRmLThiNGQtOTJhNTM1NWQxYTFmIiwiaXNzIjoiaHR0cHM6Ly9wYXJ0bmVyLnRsaW50ZWdyYXRpb24uY29tL2F1dGgvcmVhbG1zL1BhcnRuZXJBcGkiLCJhdWQiOiJUcmF2ZWxMaW5lLlBhcnRuZXJBUEkiLCJzdWIiOiI4NmE0YjZiZS0wYTc0LTRjYjktYjNhYi1iNDYyZWUwYmIyYmQiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJwYTMiLCJzY29wZSI6IiIsImFwaV9hY2Nlc3NlcyI6WyJjb250ZW50Il19.Nz6dyaHGyIN5IKv30oM-HrqdQBqaGdzEFrk7ACUWbfvsNCHNowg96iJrGwQbkOUSVPtQJF9Cwf1_jywP6c2UPHclzBIDp9HTsYdVM5QS_k9ecs0GCiI8ACBqld3yatY4dJz3MRkxnU_rp0NbJJQ-uBcmg_9UCSCIc3mKR7UAosr5XOXeb4ckrFd67DK5xfofT0ykE46Qkc6nvev3AGx11fPAVsFnmmPOSnlpQzJTI7XBWbD120q5fDdksVlaiq3YoBueDEeOPFH08Ia6xdTVjIf_zsyOEKt2N8_7BTyWG_3YPThBbgn-eAgybSdeop6_eCrWTfQvX5g8qtR2e9J32A

На сайте 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:

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. Например, «Получить информацию о средствах размещения»: