Как создать собственный тип носителя (application/vnd) для веб-службы RESTful?

Я сейчас играю с REST и подумал, что правильно реализовал HATEOAS, чтобы правильно понять все концепции.

Для этого я хочу создать свои собственные типы мультимедиа (application/vnd[...]+xml и application/vnd[...]+json).

Первый вопрос: Определяет ли тип носителя контракт между моим сервером и клиентом?

Тип мультимедиа будет определять форматы моих сообщений, поэтому мне нужно добавить схему XML и схему JSON для новых типов мультимедиа (чтобы клиенты REST знали, что приходит в сообщениях и что отправлять обратно).

Я провел некоторое исследование в Интернете, но подробности о том, как это сделать, отсутствуют. Включает ли это только написание исчерпывающей спецификации/документации или необходимо реализовать некоторые технические шаги? (Мне не нужно регистрировать его в IANA, не так ли?)

Как можно создать новый полнофункциональный тип носителя application/vnd? и о чем вам нужно позаботиться, чтобы клиенты могли правильно его использовать?


rest media hateoas hypermedia restful-architecture
person JohnDoDo    schedule 04.02.2013    source источник
comment
Для всех, кто проходит мимо: книга RESTful Web API – замечательная книга и просто должен прочитать, если вы заинтересованы в правильном выполнении REST.   -  person Torben Koch Pløen    schedule 14.12.2014

Ответы (3)


arrow_upward
26
arrow_downward

@ДжонДоДо

Один первый вопрос: определяет ли тип носителя контракт между моим сервером и клиентом?

Да, тип носителя является частью контракта. Контракт в REST API не является статическим, в отличие от SOAP (т.е. WSDL). Контракт определяется комбинацией базового протокола (например, HTTP), URI и типов мультимедиа (не запрещено использовать несколько типов мультимедиа вместе). Тип носителя определяет модель данных, модель обработки, элементы управления гипермедиа (например, аннотированные ссылки, формы ввода и т. д.) и поддержку включения дополнительной информации, специфичной для приложения, описанной отношениями ссылок, именами элементов, идентификаторами, именами классов и т. д.

Тип мультимедиа будет определять форматы моих сообщений, поэтому мне нужно добавить схему XML и схему JSON для новых типов мультимедиа (чтобы клиенты REST знали, что приходит в сообщениях и что отправлять обратно).

Вам нужно только определить общие схемы, которые охватывают структуру документа. Вам не нужно определять отдельные схемы для отдельных сообщений. Ваши сообщения должны соответствовать структуре, определяемой типом носителя.

Как создать новый полнофункциональный носитель application/vnd? и о чем вам нужно позаботиться, чтобы клиенты могли правильно его использовать?

  1. Опишите его (т.е. напишите спецификацию формата);
  2. Зарегистрируйтесь в IANA: http://www.iana.org/cgi-bin/mediatypes.pl регистрация типа носителя в дереве vnd.* занимает почти неделю.
person ioseb    schedule 12.02.2013
comment
Большое спасибо за это! Так что, в конце концов, все, что нужно, — это просто написанная спецификация. Правильный? - person JohnDoDo; 12.02.2013
comment
Для ясности по пункту 2: Рекомендуется зарегистрировать его, но это не является строгим требованием. См. stackoverflow.com /вопросы/29121241/ - person Wim Deblauwe; 25.10.2019

arrow_upward
4
arrow_downward

Взгляните на API RESTful Hypermedia за три простых шага

Ваш медиа-тип должен описывать типы данных, но я бы не стал делать это со схемой XML. Если вы используете XML-схему, я настоятельно рекомендую использовать свободную стратегию управления версиями, в противном случае вы обнаружите, что вам понадобится новый медиа-тип каждый раз, когда вы захотите добавить новый элемент или атрибут.

person Tom Howard    schedule 04.02.2013
comment
Итак, если я правильно понял: это просто хороший документ, описывающий тип носителя, чтобы разработчики знали, как кодировать клиент? - person JohnDoDo; 07.02.2013
comment
правильно, и им нужно сопротивляться желанию оптимизировать, заставляя своих клиентов переходить непосредственно к определенным URL-адресам. Клиент начинает с общеизвестного корневого URI (например, example.org/list) и просто следует ссылки и формы, чтобы добраться туда, куда он хочет. например, GET example.org/list говорит мне, что я могу получить открытые элементы по адресу example.org/list/?open. У разработчиков возникает соблазн внедрить это в свой клиент, но завтра GET example.org/list может рассказать нам, что открытые элементы находятся по адресу GET example.org/openlist или даже otherexample.org/list - person Tom Howard; 07.02.2013
comment
Я также должен упомянуть, что вы должны попытаться свести к минимуму внеполосную информацию, которая передается в вашем медиа-документе, и максимизировать внутреннюю информацию, которую клиент может получить из ответов. Чем больше внеполосной информации используют ваши клиенты, тем теснее они будут связаны с вашим сервером, что затрудняет его развитие. - person Tom Howard; 07.02.2013
comment
Под внешней информацией вы подразумеваете не определять форматы и местоположения URL-адресов или также ограничивать информацию о содержании сообщения? (например, вы предложили не добавлять схему XML/JSON в свой ответ). Это еще одна проблема, которую я имею с ресурсами, которые я прочитал. Я понимаю, что навигация не должна быть априорной информацией для клиента, но как насчет содержания сообщения!? Клиенту нужна априорная информация о содержании сообщений для отправки/получения, иначе он не будет знать, что делать с сообщениями? Правильный? Или я что-то упускаю? - person JohnDoDo; 08.02.2013
comment
Что касается ответов, которые получил ваш клиент, да, он будет ожидать определенного ответа; однако клиенту все равно, есть ли в ответе дополнительная информация. Что касается запросов, которые вы отправляете, это должно определяться исключительно ссылками и формами в ответах, которые вы получаете. - person Tom Howard; 11.02.2013

arrow_upward
2
arrow_downward

Определяет ли тип носителя контракт между моим сервером и клиентом?

Нет, тип носителя определяет только тип (например, приложение) и подтип (например, json) данных.

Как создать новый полнофункциональный носитель application/vnd? и о чем вам нужно позаботиться, чтобы клиенты могли правильно его использовать? (http://www.ietf.org/rfc/rfc2046.txt?number= 2046)

Если вы решите создать свой собственный подтип носителя и ожидаете, что он будет широко использоваться, его следует зарегистрировать в IANA (http://www.iana.org/assignments/media-types). Это стандартный способ обмена внеполосной информацией с потенциальными клиентами.

person subodh    schedule 11.02.2013