recoder | JSON APIs (Reply)

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

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

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

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