Редактируйте руками !!только!! если вы знаете, что делаете. Страница была
сгенерирована автоматически {{ when }} с машины {{ hostname }}.

Есть АПИ которое использует фронтэнд вики, входная точка у него %%/_api/frontend/%%.
Есть АПИ с входной точкой %%/_api/v1/%%. Оно сделано для роботов и документация для него
в разработке.

API отвечает по адресу %%https://wiki-api.yandex-team.ru/_api/frontend/...%%

Например, запрос %%/_api/frontend/users/puroman/.comments%% вернет список комментариев к странице %%users/puroman%%.

Запрос без параметров формата возвращает веб-интерфейс django-rest-framework с читабельно оформленным json
и кнопками эмуляции различных типов запросов (POST, PUT, DELETE), если данный ресурс их позволяет делать.

== Можно работать из браузера

Любой урл из АПИ вы можете запросить из браузера, АПИ поддерживает аутентификацию по куке, например
https://wiki-api.yandex-team.ru/_api/frontend/homepage/.files?format=json.

Когда вы работаете с АПИ из браузера, помните, что важно использовать GET-параметр %%format=json%%. Сравните:

  * https://wiki-api.yandex-team.ru/_api/frontend/.favorites/bookmarks?format=json
  * https://wiki-api.yandex-team.ru/_api/frontend/.favorites/bookmarks

наш фреймворк выводит описание ручки, ее ответ и форму для запросов в эту ручку:
https://jing.yandex-team.ru/files/chapson/2014-10-14_1200.swf (помните, что из-за бага в фреймворке
в эту ручку нельзя отправлять кириллицу, только ascii-символы).

Когда вы работаете с ручками и методами POST, PUT, DELETE из консоли, параметр %%format=json%% можно заменить на заголовок %%Content-Type: application/json%%.
Они равнозначны.

== Даты и время

В API для фронтэнда все даты указаны в таймзоне пользователя. Они присылаются строками вида "2013-04-03T17:08:40+03:00".
Если пользователь анонимный или по какой-то причине его таймзону узнать невозможно, выбирается таймзона по-умолчанию.
Сейчас это Europe/Moscow.

== Таймауты, ретраи

Ходите в таймаутом в 5 сек на чтение, 10 секунд на запись. Ретраиться можно.

== Существующие клиенты

Пока нет.

== Аутентификация

АПИ аутентефицирует пользователя либо по куке, либо по oAuth-токену. Если вам нужно попробовать АПИ,
используйте куку и запрашивайте АПИ прямо из браузера. Если вам нужно работать с АПИ через робота,
закажите отладочный oAuth токен: http://api.yandex.ru/oauth/doc/dg/tasks/get-oauth-token.xml.
Внимание: в документации везде указан хостнейм oauth.yandex.ru, но в интранете вам нужно использовать
oauth.yandex-team.ru.

== Общий вид ответа

=== Запрос обработан нормально

В "data" содержится "payload", полезная нагрузка ответа от API. В полях user и debug содержится вспомогательная информация.

%%(js)
{
    "data": {
        // данные, специфичные для данного запроса
    },
    "user": {
        // пользователь, сделавший запрос
    },
    "debug": {
        // дебаг информация, в продакшне может быть отключена
    }
}
%%

=== При запросе произошла ошибка

%%(js)
{
    "error": {
        "error_code": "CLIENT_SENT_INVALID_DATA",  // код ошибки
        "level": "ERROR",  // "ERROR" или "INFO"
        "debug message": "Client sent invalid data, please correct your request",
        "errors": {
          "title": ["Это обязательное поле."],
          "body": ["Слишком много смысла в этой статье, попробуйте разбить ее на две страницы."]
        },
        "message": ["Пользователь не имеет доступа к этой странице"]
    },
    "user": {
        // пользователь, сделавший запрос
    },
    "debug": {
        // дебаг информация, в продакшне может быть отключена
    }
}
%%

Поля errors и message нужно показывать пользователю. В поле errors содержится маппинг,
по которому можно понять какое поле из запроса было неправильно заполнено, и как это исправить.
Например, там может быть написано, что ваш текст слишком большой и его надо разбить на две страницы.
В поле message отображаются ошибки, которые не относятся к полям запроса, но которые не позволяют
обработать запрос. Например: "Сервис перешел в рид-онли режим", "У пользователя нет доступа к запрошенной странице".

Каждое поле в errors представлено списком, значение поля message - тоже список.

Все ошибки представлены на языке пользователя. Все ошибки заключены в список, это сделано для того случая,
когда бекэнд захочет прислать сразу несколько ошибок о каком-то поле. Клиент должен быть к этому готов:
он должен выводить сообщения про каждое поля запроса в виде списка.

Исключение составляют ошибки, которые не могут быть вызваны пользовательским вводом. Для них переводы не предоставляются.

Поле debug_message нужно для отладки. Его не нужно показывать пользователю.

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

Эта и другая информация есть в рассылке https://ml.yandex-team.ru/thread/2370000001638208192/

== Доступные ручки в API

{% for handle in api_handle_names %}
{% templatetag openvariable %}include page="!/{{ handle }}" nomark notitle {% templatetag closevariable %}
{% endfor %}

== Все возможные ошибки
{% include 'utils/rest_framework/all_possible_errors.txt' %}
