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

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

Это пост с кратким пересказом очередной главы книги "API Design Patterns" Дж. Дж. Гивакса, посвящённой кастомным методам API.

Зачем нужны пользовательские методы? Иногда стандартные методы API не подходят для определенных задач и при их использовании может возникать чувство, будто мы слепо следуем букве закона, но не его духу. Например, нужно отправить письмо или перевести текст. Стандартные методы должны выполнять одно действие, например, обновление данных, а не быть использованными для решения более сложных задач, таких как отправка письма, что может приводить к путанице.

Сложность возникает из-за того, что стандартные методы API часто не подходят для действий с сайд эффектами. Например, если вы используете метод PATCH, чтобы изменить статус письма с "Черновик" на "Отправлено", это скорее всего не только обновит данные, но и выполнит сайд эффект, такой как отправка письма. В этом случае использование стандартного метода может сделать API сложным и трудным для понимания, так как оно нарушает принцип единственной ответственности.

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

Как устроены пользовательские методы? Пользовательские методы обычно используют HTTP-метод POST (реже GET или DELETE) и автор рекомендует использовать путь запроса с двоеточием в конце и названием действия. Например, POST rockets/1234567:launch. Это позволяет явно указать, что происходит действие с сайд эффектом, а не просто обновление данных.

Пользовательские методы могут быть stateless - то есть, работать с данными, но не сохранять их состояние. Это полезно, например, для перевода текста, где результат не зависит от сохраненных данных - POST /text:translate. Но, stateless методы могут требовать некоторого контекста, например, для операций с оплатой. Например, POST /project/payment:process — stateless метод, привязанный к проекту и обработкой платежа.

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

#заметки_из_книг

Ⓒ Айнур пишет … 📝