ссылки о hypermedia APIs
я как-то прозевал появившиеся за последний год подходы к встраиванию метаданных в JSON API, и вот недавно обнаружил целых две спецификации. Обе они пытаются вернуть в JSON что-то хорошее из XML. В частности это хорошее — гиперссылки, отсюда и такое название.
вкратце идею можно описать так: когда мы запрашиваем html-ресурс, мы обычно получаем и кучку ссылок на связанные объекты, а также возможные действия. Хочется иметь то же самое для JSON, ведь там обычно просто голые данные. Так давайте договоримся о стандартном способе прицеплять к ним ссылки и, возможно, сами связанные объекты. Hypertext Application Language (HAL) этим и ограничивается. Collections+JSON идёт дальше и определяет кучу других ограничений, поэтому и нравится мне меньше.
в тему метаданных хочу дать и ещё одну ссылку: про версионность API. Я пока что видел мало примеров этого, и лучшим вариантом мне казалось включение версии непосредственно в адрес: /api/v2/resource. Однако Peter Williams разумно замечает, что такой подход приводит к тому, что один и тот же ресурс с разными версиями API — это разные ресурсы. Он же предлагает и красивый альтернативный способ добавлять версию в API: Accept: application/vnd.mycompany.myapp-v2+xml. Концептуально это мне очень нравится, хотя не могу не обратить внимания на недостатки: такой интерфейс сложнее исследовать браузером, и тип всё-таки нужно регистрировать. Но красиво.