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

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

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

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

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

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

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

Ответ 1

@JohnDoDo

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

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

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

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

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

Опишите его (т.е. спецификацию формата записи);
Зарегистрировать в IANA: http://www.iana.org/cgi-bin/mediatypes.pl регистрировать тип носителя под деревом vnd. * для регистрации требуется около недели.

Ответ 2

Посмотрите API RESTful Hypermedia в трех простых шагах

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

Ответ 3

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

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

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

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