Современный REST API❓ Встречайте пользовательские методы 🚀

При проектировании REST API мы как разработчики часто встречаемся с дилеммой что операция которую мы хотим добавить не вписывается дизайн стандартных методов. И хотя технически мы можем просто игнорировать шаблон и задействовать любой путь для этой операции но, такие решения обычно приводят к запутыванию интерфейса и повышают порог входа для потребителей. Чтобы решить проблему повышенного порога входа и сохранить простоту использоваения предлагаю Вам ознакомиться с пользовательскими методами.

Пример проблемы

Представьте что Вы разрабатываете API для системы отправки E-Mail писем. В Вашей системе есть ресурс Letter. Выглядит он пример так:

Letter {
    string address
    enum state: draft|sent
    string subject
    ...
}

Для этого ресурса Вы разработали стандартные методы CRUD.

POST /letters
GET /letters/{id}
DELETE /letters/{id}
PATCH /letters/{id}

А теперь Вам требуется отправить данное письмо. Какое решение Вы можете использовать из стандартных методов. Можно использовать Patch для обновления поля state

PATCH /letters/{id}
{
    "state": "sent"
}

Когда Ваше приложении получает от клиента состояние «Отправлено», тогда инициируется соединение с почтовым сервером и отправляется письмо.

Какие проблемы у данного подхода:

1. Поле state изменяется пользователем, а должно только системой.
2. Отправка письма операция не дешевая и требует инициализацию соединения напр. с сервером SMTP. Может существенно замедлить операцию.
3. Является побочным эффектом который добавляет зависимость от внешнего сервиса.

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

Пользовательские методы

Пользовательские методы это те же самые вызовы API которые выходят за рамки стандартных методов и не наследуют их ограничения. Они отлично подходят для операций с побочными эфектами.

POST /letters:send

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

POST / letters : send
----   -------   ----
Метод   Ресурс     Действие

HTTP глагол в большинстве случаев будет POST. Иногда может использоваться GET.

Действие рекомендуется разделять с помощью символа :, а не слеша(/), так как это вносит путаницу, где действие, а где подресурс.

Не рекомендуется использовать предлоги with или for. Например CreateLetterForAdmin, такие операции должны быть сформулированы с помощью стандартных. Пользовательские методы не вляются механизмом для параметризации стандартных.

Ресурс или коллекция

Как и стандартные методы, пользовательские, могут быть ориентированны как на ресурсы так и на коллекции ресурсов. Например:

POST /letters/{id}:send // Отправить письмо с конкретным ID
POST /letters:send // Отправить множество писем
{
    "ids": [{id}, {id}, ...]
}

Заключение

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