Сколько пользовательских типов MIME в веб-API RESTful? - PullRequest
Новая
       29

Сколько пользовательских типов MIME в веб-API RESTful?

6 голосов
/ 21 марта 2012

Должен ли веб-API RESTful использовать настраиваемый тип MIME для конкретного поставщика для каждого основного класса ресурсов (например, Customer, Reservation, HotelRoom и т. Д.) Или API должен совместно использовать один тип MIME для конкретного поставщика для всех ресурсов?

С одной стороны, каждый ресурс отличается, так как он имеет разные поля и, например, конечная точка, которая может принимать новых клиентов, не может принимать новые заказы.

Однако, Практика наихудшего отдыха предполагает, что это плохая вещь (tm), так как это может усложнить синтаксический анализ на стороне клиента, но не дает подробностей помимо этого.Я определенно вижу в этом серьезную проблему.Следуя подходу типа «за ресурс», кажется, что вы, возможно, даже продолжите создавать собственный тип для каждого вида коллекции со встроенными неанонимными сущностями.

Ответы [ 4 ]

2 голосов
/ 05 августа 2015

Думайте прагматично. Тип MIME определяется как «Тип медиа в Интернете - это идентификатор из двух частей для стандартизации форматов файлов через Интернет». Это означает, что если формат данных изменяется, (TXT-> HTML-> JSON-> XML-> YAML-> CSV -> ...) тип MIME необходимо изменить.

Тем не менее, есть и другие вполне допустимые виды использования, одно из которых было упомянуто выше Джошуа Белденом Вот пример , как GitHub использует MIME-тип для определения версии API.

Текущая версия

По умолчанию все запросы получают версию API версии 3. Мы рекомендуем вам явно запросить эту версию через Accept заголовок.

Принять: application / vnd.github.v3 + json

Имеет смысл, что компоновка данных запроса v2, отправленного в версию API v3, будет несовместимой, даже если они находятся на одном и том же URL-адресе (и наоборот). Это также помогает уменьшить изменения, необходимые для перехода от одной версии API к другой (например, вам не нужно обновлять URL).

Тем не менее, это не означает, что ваше приложение должно по умолчанию использовать пользовательский тип MIME для того, чтобы "обеспечить будущее" для API конкретной версии. Если ваше приложение не имеет большого внешнего API-интерфейса со многими общедоступными потребителями, вам, скорее всего, не нужен пользовательский тип MIME версии.

Кроме того, ваши конечные точки REST API должны определять структуру производимых и потребляемых данных, а не тип MIME. Например, GET "/ Customers / 5" должен создавать только те данные, которые были сериализованы из вашей сущности Customer. И ПОСТ "/ Оговорки" следует использовать только те данные, которые будут десериализованы для вашей сущности резервирования. Это означает, что сериализация вашей конечной точки будет обрабатывать проверку синтаксиса и должна возвращать код уровня 400 и объяснять, что предоставленные данные не структурированы должным образом.

Еще один пример из API GitHub, который подчеркивает это поведение. 

 HTTP/1.1 422 Unprocessable Entity
 Content-Length: 149

 {
   "message": "Validation Failed",
   "errors": [
     {
       "resource": "Issue",
       "field": "title",
       "code": "missing_field"
     }
   ]
 }

Подводя итог, можно сказать, что большинство платформ сериализации "из коробки" ожидают обработки "application / json" и "application / xml". Хотя вы, конечно, можете добавить пользовательский тип MIME для конкретного поставщика, зачем делать это, если у вас нет веских причин для этого?

Извините, если я только что создал вопрос зомби с этим ответом.

2 голосов
/ 21 марта 2012

Расширение комментария, оставленного @deceze: Вам оно не понадобится. Возможно ли, что вы путаете "настроенные для конкретного производителя типы MIME" с чем-то другим?

Я не понимаю, почему вы не можете ограничиться отправкой application/json или application/xml для всех ресурсов (или обоих, в зависимости от запроса).

Конечно, структура каждого ресурса полностью зависит от соответствующих полей, но вы все равно можете использовать все из них как хеши JSON (если вы выбираете JSON).

0 голосов
/ 05 августа 2015

Использование типов MIME позволяет отделить ресурс REST от его представления (т. Е. Json, xml, pdf и т. Д.).Это делает вещи менее связанными, но идея состоит не в том, чтобы использовать его для определения схемы ресурса, а в его формате .

С одной стороны, каждый ресурс отличается, так какимеет разные поля и, например, конечная точка, которая может принимать новых клиентов, не может принимать новые заказы.

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

Отвечая прямо на ваш вопрос: постарайтесь как можно меньше использовать количество пользовательских типов MIME.ИМХО, вы можете использовать их для объявления разных версий вашего API, как это уже упоминалось здесь.

0 голосов
/ 02 июня 2014

Если веб-API RESTful использует настраиваемый тип MIME для конкретного поставщика для каждого основного класса ресурсов (например, Customer, Reservation, HotelRoom и т. Д.) Или если API совместно использует один тип MIME для конкретного поставщика для всех ресурсов?

Это на самом деле не имеет значения, потому что на самом деле не отделяет клиента от сервера, это всего лишь грубое решение.

Однако, Rest Worst Practicesпредполагает, что это A Bad Thing (tm), так как это может усложнить синтаксический анализ на стороне клиента, но не дает подробностей, кроме этого

Да, это правда.Вам следует использовать мелкозернистое решение, например RDF со стандартными вокаблами, например открытые связанные данные и, возможно, гидру для части REST.

...