Заметки идущего Технические заметки по веб-технологиям

Web API

Моя позиция по проектированию WebAPI следующая:

  1. API должно быть простым и понятным, тупым
  2. API должно быть единообразным
  3. API нужно стараться делать REST настолько, насколько это возможно, оставаясь в рамках здравого смысла
  4. Сущности в API должны быть обогащенными (полными), чтобы не было необходимости делать дополнительные запросы к API. Никаких полей по типу entityId, только entity:{Id:1,Name:'111'}. Обогащать тоже нужно в рамках разумного, в большинстве случаев достаточно Id, Name
  5. API не должно зависеть от технических нюансов реализации, что на клиенте, что на сервере. Все сложности - это проблема реализации, а не протокола.
  6. На вход API отправляется та же структура сущностей, что даёт API на выход. Значения, которые не менялись, не должны считаться внесенным изменением.
  7. Отсутствующие в принципе значения должны всегда иметь значение null. Поле при этом не должно пропадать, т.к. структура сущности та же
  8. Сервер должен возвращать читаемые человеком ошибки.

Статьи на тему: