Основные понятия

Введение

API Сервера совместной работы реализовано как REST через HTTP с использованием запросов GET/POST/PUT/DELETE. У всех ресурсов, таких как посты или комментарии, есть собственные URL, возможно управление этими ресурсами независимо друг от друга.

Авторизация

Авторизация в API Сервера совместной работы происходит через аутентификацию HTTP, то есть каждый запрос должен включать в себя заголовок авторизации HTTP. Для более подробной информации и примеров смотрите раздел Авторизация.

Совершение запросов

Для идентификации форматов запросов и ответов убедитесь, что заголовки Content-Type и Accept установлены в значение application/json. Любой метод API может быть вызван с заранее определённым форматом ответа (json или xml).

Пример:
api/2.0/people/@self может быть вызван как в виде api/2.0/people/@self.json - тогда данные в ответе будут в формате JSON так и api/2.0/people/@self.xml - тогда данные в ответе будут в формате XML.

По умолчанию, если в запросе не указан формат, для ответа используется формат XML (например, запрос api/2.0/people/@self вернёт данные в формате XML).

Ответы

В случае успешного ответа будет возвращён статус-код в диапазоне 200 и, в случае, если в запросе не был задан формат, ответ в формате XML. Обратите внимание, что в случае, если в результате запроса должна быть создана новая запись (новый пост, комментарий и т.д.) статус ответа будет "201 Created". При любой другой успешной операции (успешный запрос, удаление или обновление записи) код статуса ответа будет 200.

В случае неудачного запроса, будет возвращён код, отличающийся от статуса 200 и по возможности ошибка в формате XML в качестве содержимого ответа. К примеру, если запрошенная запись не может быть найдена, ответ HTTP будет выглядень следущим образом:

HTTP/1.1 404 Not Found

Ограничения

Вы можете выполнить до 500 запросов в течение 10 секунд с одного IP-адреса для одной учётной записи. Если это ограничение будет превышено, для последующих запросов будут получены ответы 503. Чтобы проверить, через сколько секунд можно попробовать снова, испольуйте заголовок Retry-After.

Условные обозначения, используемые в документации

В данной документации используются следующие условные обозначения:
{text}: означает, что текст в фигурных скобках должен быть заменён на ваши собственные данные (ID, поисковый запрос и т.д.)