Современный 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" }
Когда Ваше приложении получает от клиента состояние “Отправлено”, тогда инициируется соединение с почтовым сервером и отправляется письмо.
Какие проблемы у данного подхода:
- Поле state изменяется пользователем, а должно только системой.
- Отправка письма операция не дешевая и требует инициализацию соединения напр. с сервером SMTP. Может существенно замедлить операцию.
- Является побочным эффектом который добавляет зависимость от внешнего сервиса.
Рекомендуется оставлять стандартные методы чистыми и предсказуемыми, не перегружать их обязаностями.
Пользовательские методы
Пользовательские методы это те же самые вызовы 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. Не стоит злоупотреблять ими, и использовать только тогда когда они действительно нужны, когда стандартные методы точно не подходят под ваши требования.