Дизайн API: HATEOAS, json, управление версиями и типы носителей

Мне нравится концепция REST HATEOAS о том, чтобы сделать ваш API доступным через гиперссылки. Людям нравится XML с форматом ATOM для ссылок, и вам, возможно, даже не понадобится версия вашего API. Но, я только делаю JSON, и я хочу, чтобы версия моего API и по-прежнему делать HATEOAS.

Кажется, что лучше всего было бы использовать тип носителя поставщика, как в application/vnd.me.v1+json, но тогда все эти разговоры об отсутствии формата для гиперссылок в JSON и таких вещах, как HAL, JSON+Collecton и Siren, которые имеют свои собственные носители тип.

Итак, вот мое замешательство. Во-первых, зачем указывать формат через тип носителя? Почему включение ссылок в JSON не может быть просто соглашением, которому следуют клиенты? Разве не так браузер hm-json обнаруживает ссылки?

И, если его нужно определить как тип носителя, работает ли что-то подобное?

application/vnd.me.v1.hal+json

Кто-нибудь?

1 4
api json hateoas

1 ответ:

Во-первых, зачем указывать формат через тип носителя?

Да, вы можете иметь соглашение о формате ссылок, однако любое соглашение может быть обнаружено только после распаковки тела сообщения HTTP. Поскольку типы носителей являются заголовками, тело сообщения может быть принято или отклонено как единое целое. Это делает обработку запросов более эффективной для потребителей, которые не поддерживают предлагаемые типы носителей.

Приложения/донгов.меня.В1.Хэл+в формате JSON

Насколько я понимаю, типы носителей могут быть ограничены до уровня, соответствующего описываемому вами API. Таким образом, вы можете выбрать тип носителя для одного представления, группу представлений, которые все связаны с одной и той же службой, или один тип носителя для всей организации.

Это хороший пост SO с учетом типов носителей:

2