API для sishot.ru

Типы данных

API умеет возвращать данные в форматах JSON и XML. Форматом ответа можно управлять с помощью заголовка запроса Accept:

Accept: application/json — выдать данные в формате JSON;
Accept: application/xml — выдать данные в формате XML.

По умолчанию JSON, он же указан в примерах.

Целые числа, если не указано иное, являются беззнаковыми 64-разрядными целыми числами.

Обязательные параметры запросов выделены.

Урлы и методы

Базовый урл обязательно включает в себя версию API:

https://sishot.ru/api/v1

Важно сделать базовый урл в приложении настраиваемым, потому что со временем он может меняться: http поменяется на https, сменится мажорная версия API и так далее…

Все урлы API даны относительно базового урла. Например, указанный /image разворачивается в https://sishot.ru/api/v1/image.

К любому из урлов можно применять методы HEAD и OPTIONS. После запроса OPTIONS в ответном заголовке Allow будет содержаться список доступных для этого урла методов. Например OPTIONS /image → Allow: POST, HEAD, OPTIONS, а OPTIONS /image/5hBVPemcAAXW → Allow: GET, HEAD, OPTIONS.

Если какой-либо метод к данному урлу неприменим, код ответа — 405, а ответный заголовок Allow содержит список доступных для этого урла методов (как и в OPTIONS).

Более подробный список используемых HTTP-кодов ответа см. ниже.

`POST /image`

Создаёт новое изображение.

Если параметры пользователя (token) не переданы, файл будет создан анонимно (без авторства определённого пользователя).

Параметры:

file — файл, закодированный POST-методом (multipart/form-data);
caption — подпись к изображению (строка до 250 символов);
token — токен авторизации пользователя (пока недоступно).

Формат JSON-ответа:

{
	"id": "5hBVPemcAAXW",    // идентификатор — строка
	"name": "гимн.png",      // исходное имя файла — строка
	"caption": "подпись",    // подпись к изображению — строка, может быть `null`
	"type": "image/png",     // MIME-тип файла — строка
	"size": 100666,          // размер файла — 32-битное беззнаковое целое число
	"url": "https://…",      // ссылка на просмотр файла — строка
	"userId": null           // идентификатор автора — целое число, может быть `null`
}

Если валидация данных не увенчается успехом (код ответа — 422), тело ответа будет содержать список полей запроса и их сообщения об ошибках.

После успешного создания (код ответа — 201), в ответном заголовке Location будет указан урл для получения информации о файле методом GET (см. ниже).

Обратите внимание, что значение заголовка Location не равно значению поля url в теле ответа, у этих урлов разные смыслы: первая ссылка предназначена для получения информации о файле, вторая — для просмотра файла на сайте. (Например, https://sishot.ru/api/v1/image/5hBVPemcAAXW и https://sishot.ru/i/5hBVPemcAAXW.)

`GET /image/@id`

Получить информацию об изображении с идентификатором @id.

Идентификатор — строка символов a—z, A—Z, 0—9, -, _. Например, 5hBVPemcAAXW. Регвыр для валидации строки — /^[a-zA-Z0-9_-]+$/.

Параметров нет.

Возвращает такой же JSON-объект, как и POST-метод.

HTTP-коды ответов

200 — всё прошло хорошо;
201 — ресурс создан, ответный заголовок Location содержит урл новосозданного ресурса;
204 — запрос обработан успешно, тело ответа пусто (например, при DELETE-запросе);
304 — ресурс не изменён, клиент может использовать закешированную версию;
400 — плохой запрос, неверные параметры и т. п.;
401 — ошибка аутентификации;
403 — ошибка доступа, текущий аутентифицированный пользователь не имеет прав на доступ к этому урлу;
404 — запрошенный ресурс не существует;
405 — данный метод не применим к запрошенному урлу, ответный заголовок Allow содержит список доступных методов;
415 — неподдерживаемый тип данных, запрошенный тип содержимого или его версия недоступны (не JSON и не XML);
422 — ошибка валидации данных (например, в ответ на POST-запрос, тело ответа содержит текст ошибки;
429 — слишком много запросов, ответный заголовок X-Rate-Limit-Reset содержит время в секундах, когда ограничение будет снято, и запрос можно будет повторить;
500 — внутренняя ошибка сервера, клиентское приложение не виновато.

P.S.

С Днём победы!

/**
 * API для sishot.ru
 *
 * @author MaximAL
 * @date 2015-05-09 С Днём победы!
 * @time 1:15
 * @version 1.0
 * @since 2015-05-09 Первая версия документа.
 * @copyright © MaximAL, Sijeko 2015
 **/