Listen IT

🛠 Продолжаю выкладывать переводы постов-шпаргалок из LinkedIn от Alex Xu.



Сегодня обсудим 8 кратких советов по проектированию эффективного API:



🔹 Доменный подход (Domain Model Driven)

При проектировании структуры URL для RESTful API можно опираться на доменную модель.



🔹 Выбираем подходящие HTTP-методы

Определение нескольких базовых HTTP-методов может упростить разработку API. Например, использование PATCH может часто оказаться проблемой для команд (интересный момент кстати, мы обычно PATCH используем, но понимаю, что при реализации, например, могут возникнуть трудности с конфликтами и конечным использованием - нужно нормально его документировать. Да и остальные методы, не такие классические, тоже иногда могут понадобиться, так что тут не вполне соглашусь. В общем, можно похоливарить в комментариях).



🔹 Правильная реализация идемпотентности

Проработка идемпотентности при проектировании заранее может повысить надёжность API. Например, метод GET всегда идемпотентный, но POST часто нужно проектировать с учётом того, чтобы он стал идемпотентным.



🔹 Выбираем подходящие HTTP-коды

Лучше выделать ограниченный набор HTTP-кодов, чтобы упростить разработку приложения.



🔹 Версионирование

Использование версий API при проектировании может упростить процесс обновлений.



🔹 Семантика в URL

Использование семантических URL позволяет проще понимать API, чтобы пользователи могли найти нужный метод в API-документации. Например, используем имя ресурса вместо глагола и множественные числа существительных (где это возможно).



🔹 Пакетная обработка

Используем слова "batch" / "bulk" в конце строки URL для обозначения массовых действий.



🔹 Query-параметры

Использование набора устоявшихся параметров в URL делает API более гибким. Например, пагинация, сортировка, фильтрация и др.