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

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


HTTP
====

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


Методы
------

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

- :method:`GET`

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

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

- :method:`POST`

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

- :method:`PATCH`

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

- :method:`DELETE`

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


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

- :header:`Accept`

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

- :header:`Content-Type`

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

.. _header-authorization:

- :header:`Authorization`

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

- :header:`X-Partner`

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

Коды ответа
-----------

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


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

Если не указанно иного, в теле запросов и ответов используется `JSON <http://json.org/>`_.
При работе с коллекциями, возврашается массив объектов, при работе с конкретным объектом -- сам объект.


.. _basic/auth:

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

Для авторизации по ключу, значение :ref:`заголовка "Authorization" <header-authorization>`
имеет префикс ``key`` (``key<пробел>``).

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


.. _basic/field-schema:

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

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

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

:ref:`Пример использования <ex/fields-schema>`.


Сервера
=======

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

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