JSON APIs

[recoder]

А подскажите мне, коллеги-программисты, какой нонеча самый кошерный способ правильно описывать HTTP APIs? Ну вот так, чтобы свой обычный REST JSON API, описать его один раз и чтобы дальше всё само получилось: документация, клиенты для скриптовых (и не только) языков, какой-нибудь online playground, и всё такое?

Мы в нашей конторе пять лет назад, когда внедряли REST, ничего зрелого и толкового не нашли, и поэтому запилили свой велосипед: Sleepwalker. Это потом бурным цветом расцвели RAML, Swagger, WADL и прочие, а у нас уже наросли кучи полезного code base.

Вот я и думаю - если бы новый проект начинать сейчас, то что бы следовало взять за основу? Там же только на первый взгляд всё несложно, а чуть углубился в детали - и из-под каждой по дьяволу мерещится. А вдруг хочется поддержать не только JSON, а например ещё и XML? А если захочется какой-нибудь CSV или вообще blob наружу выдать? А как ошибки документировать? А как HTTP errors пересекать с ошибками приложения? А как bulk-операции реализовывать? И прочее, и прочее, и прочее...

С другой стороны - у всех же разработчиков должны быть точно такие же общие проблемы (даже если они их не замечают). А значит и общие решения должны быть, и на исходе 2016-го года они уже должны были выкристаллизоваться. Так и где же они?!

Comments

[ulrith.livejournal.com]

Наверное в ru_root лучше, вопрос-то хороший...

[recoder]

Не, там мне бородатые в бубен дадут. Это ж не админская задача, а внутренне-программерская.
А вот где тут модное хипстерьё тусит - я не знаю...

[katren.livejournal.com]

swagger и/или graphQL

[recoder]

Swagger - да, неплох, но как мне кажется уж слишком Java-ориентирован.

GraphQL - оригинален, но он какой-то неэлегантный. Да и пацаны на районе его не любят...

[r3code.livejournal.com]

Отвечу тебе тут, чтобы не потерялось. Новое веяние JSON-LD вроде бы тот же JSON, только к нему примазали одно поле @context в котором описан весь словарь путем соединения названия атрибута с адресом в schema.org. Вроде логично - общий словарь, такая себе советская энциклопедия. Можешь прочитать один раз потом на лету понимать о чем в каждом поле. И вроде даже словари можно разные указывать.
Вот Яндекс его уже понимает https://yandex.ru/support/webmaster/json-ld/about.xml
И вот о нем еще https://texterra.ru/blog/chto-takoe-format-json-ld-i-pochemu-on-luchshe-schema-org.html

Я думаю, раз у вас уже был свой велосипед, то Вам сравнить его с другим будет проще. Хотелось бы услышать ваши мысли насчет JSON-LD велосипеда )

[sadretdinov alexandr (from livejournal.com)]

Так себе идейка смешать данные и их описание. Очень избыточно на мой взгляд.
з.ы. Сорри за некроответ :)