API для sishot.ru

Новая версия апи находится в разработке...

Типы данных

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

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

Урлы и методы

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

https://sishot.ru/api/v2

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

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

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

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

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

`POST /images`

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

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

Параметры:

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

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

{
	"id": "01kqfbgzswe85a140653knr6xe",         // Идентификатор изображения
	"alias": "j9roWTYiFTg9",                    //
	"name": "Screenshot.png",                   // Исходное имя файла
	"caption": "asdfasdf",                      // Подпись к изображению; может быть `null`
	"path": "2026-04",                          //
	"file": "j9roWTYiFTg9.jpg",                 //
	"type": "image/jpeg",                       // MIME-тип файла
	"size": 478007,                             // Размер файла
	"width": 1080,                              //
	"height": 1920,                             //
	"has_alpha": false,                         //
	"avif": null,                               //
	"avif_size": null,                          //
	"rotate": 0,                                //
	"client": "api",                            //
	"access_token": "JWJc1iuFNnyHOxK1FtRMm",    // 
	"user_id": null,                            // Идентификатор автора; целое число, может быть `null`
	"avif_generated_at": null,                  //
	"png_optimized_at": null,                   //
	"last_access_at": null,                     //
	"created_at": "2026-04-30T14:08:46Z",       //
	"updated_at": "2026-04-30T14:08:46Z",       //
	"url": "http://localhost/i/j9roWTYiFTg9"    // ссылка на просмотр файла — строка
}

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

После успешного создания (код ответа — 201).

`GET /images/{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 — внутренняя ошибка сервера, клиентское приложение не виновато.