Базовые понятия

В этом разделе описаны общие положения API TicketsCloud.

HTTP

В TicketsCloud используется стандартный JSON REST API.

Методы

В TicketsCloud используются следующие методы:

  • GET

    Получение объектов.

    В ресурсах используется, как для коллекций (например: GET /v1/resources/events), так и для конкретных объектов (например: GET /v1/resources/events/:id).

  • POST

    Создание нового объекта. Применяется к коллекциям. В ответе возвращается созданный объект.

  • PATCH

    Изменение созданного объекта. Применяется к объекту. В ответе возвращается изменённый объект.

  • DELETE

    Удаление или действие отмены объекта. Применяется к объекту. Ответ с пустым телом и кодом 200.

Заголовки HTTP-запросов

  • Accept

    Крайне желательно указывать этот заголовок как application/json.

  • Content-Type

    Крайне желательно указывать этот заголовок как application/json.

  • Authorization

    Заголовок авторизации.

  • X-Partner

    Id авторизованного партнёра.

Коды ответа

Коды ответа стандартные и описаны в спецификации протокола HTTP (RFC 2616).

Тело запроса и ответа

Если не указанно иного, в теле запросов и ответов используется JSON. При работе с коллекциями, возврашается массив объектов, при работе с конкретным объектом – сам объект.

Авторизация по ключу

Для авторизации по ключу, значение заголовка «Authorization» имеет префикс key (key<пробел>).

Пример заголовка: Authorization: key 0123456789abcdef0123456789abcdef

DSL схемы ответа

Для того, чтобы ограничить или расширить ответ, применяется «схема». Она, схема, указывается в query параметре fields-schema и имеет следующую структуру: field_1,field_2,reference{ref_field_1,ref_fields_2}. Схему можно применять как для GET-запросов, так и для POST/PATCH, точно так же передавая её в URL.

Не рекомендуется делать очень грубокие схемы для запросов к коллекциям, потому что в таком случае запрос будет строится дольше и может быть отменён по таймауту.

Пример использования.

Сервера

Наш продакшен сервер доступен по адресу https://api.ticketscloud.org. Не рекомендуется использовать его для отладки интеграции.

Для этих целей есть стейджинг сервер, доступный по адресу https://stage.ticketscloud.org. Данные на этом сервере каждую ночь сбрасываются.