Стандартные методы API

Стандартные методы API

Обзор очередной главы из "API Design Patterns" Дж. Дж. Гивакса о стандартных методах.

Использование стандартных методов в API — это способ сделать интерфейс понятным и предсказуемым. Когда пользователь может быстро разобраться, как работает API, это говорит о грамотном проектировании. RESTful API особенно выигрывает от использования привычных методов: пользователю не нужно заново учить подходы для каждого ресурса — всё стандартно и знакомо.

Согласованность. Когда проектируешь API, важно выдерживать единообразие в ответах на одни и те же запросы. Например, что возвращать при попытке удалить несуществующий ресурс: 200 OK или 404 Not Found? Здесь дело не только в выборе, но и в том, чтобы API всегда отвечало одинаково — это снижает двусмысленность и добавляет надёжности.

Не для каждого ресурса нужны все методы. В API может быть что-то избыточным, и если так, возвращаем 405 Method Not Allowed, а не 404 Not Found. Это говорит пользователю, что ресурс существует, но метод не поддерживается. Стандартные методы применяют там, где это обосновано, чтобы пользователи знали, чего ожидать.

Идемпотентность и побочные эффекты. Стандартные методы не должны оставлять после себя "хвостов". Метод Create не должен инициировать какие-то сторонние процессы (например, отправку email), а GET должен только возвращать данные, не изменяя их состояние. Никаких сюрпризов.

Что делают основные методы?

- GET — для получения ресурса по ID. Должен быть идемпотентным: если данные не изменялись, повторный запрос вернёт тот же результат.

- LIST — чтобы получить список ресурсов. Список подстраивается под права доступа, и API возвращает только те данные, которые пользователь может видеть. Чтобы избежать лишней нагрузки, можно использовать фильтрацию. Лучше использовать фильтры в виде строк - они дают серверу гибкость и не требуют сложной типизации.

- CREATE — создаёт новый ресурс. Обычно сервер сам генерирует ID, но иногда можно доверить это пользователю. В распределённых системах возможны задержки репликации, что может вызывать ошибку 404, если изменения не успели реплицироваться по всем нодам. Чтобы такого не было, учитываем время репликации или используем паттерн длительные операции (об этом в отдельной главе).

- UPDATE — частичное обновление ресурса через PATCH. Вносятся только изменения, указанные пользователем. Если обновления касаются состояния ресурса, лучше делать отдельные кастомные методы, например, ArchiveChatRoom().

- DELETE — удаляет ресурс. Может быть идемпотентным, если API ориентируется на декларативный подход (удалить ресурс, даже если он не существует) или не идемпотентным — когда удаляются только существующие ресурсы. В ресурсно-ориентированных API обычно DELETE неидемпотентен.

- REPLACE — полная замена ресурса через PUT, включая все его поля, даже если они не известны клиенту. PUT можно использовать для создания новых ресурсов, но он не должен заменять Create, поскольку не позволяет различать создание и обновление.

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

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

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