Как выбрать протокол для API?

Question

[Сергей Соколов]

Фронтенд приложения связывается с бэкендом. Формат только JSON. По мере развития всё больше методов и "концов" и растёт зоопарк:

1. один метод возвращает JSON с массивом id или пустой массив;
   
2. другой возвращает строку с HTML-разметкой, чтобы просто вставить;
   
3. третий может отказать в ответе с сообщением для юзера «нет прав на данный объект», а может вернуть объект;
   

Надо бы унифицировать протокол, прийти к единому виду на случай нормального ответа или ошибок. Единому реестру кодов ошибок. Генерить описание этого протокола для сторонних девелоперов.

Каковы best practice?

• ВКонтакте: методы возвращают нагрузку ответа в поле response, ошибку, если возникла - в поле error (тогда response отсутствует).
  
• AWS: нагруза в теле ответа. Ошибки в коде статуса ответа.
  
• MailChimp: как Amazon
  
• Telegram: bot api в ответ на вызовы методов всегда возвращает в JSON поле "ok" которое имеет значение true или false.
  

Answer 1

[ksnk]

Для начала - унифицировать формат вывода. Можно остановиться только на json, или просто указывать формат вывода в параметрах - json/txt/html/xml. Для json - нужно будет описать и зафиксировать документацией поля возвращаемого объекта. Нужны ли другие форматы вывода - смотри по месту. txt может быть удобен для тестирования и отладки АПИ.
Если предполагается продолжительное существование проекта - нужно добавить в json поле - "версия" АПИ

Comments

[Сергей Соколов]

Формат только JSON. Мне не понятно с полями / структурой ответа. У ВКонтакте методы возвращают нагрузку ответа в поле response, ошибку, если возникла - в поле error (тогда response отсутствует).

[Станислав Б]

Сергей Соколов,

Мне не понятно с полями / структурой ответа.

Можете посмотреть на jsonapi. Делать прям по этой спецификации вероятно избыточно, но можно многое из нее почерпнуть.

[Довольный Айтишникъ]

Сергей Соколов, определите набор нужных полей и поле для ошибки, если в поле ошибки пусто - читаем остальные нужные поля, если там сообщение об ошибке - обрабатываем её

Answer 2

[Довольный Айтишникъ]

Была подобная ситуация, поступили в принципе так как советует ksnk но с одним изменением. Если запрос на апи приходит без номера версии то возвращаем ответ так, как было раньше, если в запросе указан номер версии то тут уж все по правилам. Таким образом проще было перетянуть все хозяйство на единое апи разным разработчикам.

Comments

[Сергей Соколов]

чем руководствовались, когда решали?

[Довольный Айтишникъ]

Сергей Соколов, чтоб не поломать то, что в данный момент работало, так как новое апи руководство требовало прямо сейчас, а доработать существующих клиентов которые бы его не поняли требовалось время. После того, как везде все обновили этот костылик убрали

Answer 3

[Zanak]

По поводу json есть и стандарт, я про https://ru.wikipedia.org/wiki/JSON-RPC. Возможно и не один, просто этот вспомнился первым.