Как правильно указать тип ответа для REST API?

Пилю restful сервис на Jersey. Один из методов возвращает список (например) сотрудников в одном из форматов (xml, json, binary etc).
Какой способ формирования имени ресурса правильнее выбрать, учитывая выбранный формат?
С указанием content-type:
-X GET -H "Content-Type:text/xml" -G http://super-rest/employees
-X GET -H "Content-Type:application/json" -G http://super-rest/employees
-X GET -H "Content-Type:application/octet-stream" -G http://super-rest/employees

Или с простым параметром запроса:
-X -G http://super-rest/employees?type=xml
-X -G http://super-rest/employees?type=json
-X -G http://super-rest/employees?type=binary

?

Верно ли указывать в Content-Type запроса не тип содержимого запроса (body у меня вообще нет, только URL), а именно тип ответа, который хочу получить?

На w3c и mozilla как то по разному об этом сказано..
  • Вопрос задан
  • 1135 просмотров
Решения вопроса 3
Denormalization
@Denormalization
Так есть же специальный заголовок Accept, в котором клиент указывает какие форматы он поддерживает.
Т.е:
- Accept: application/json
- Accept: text/xml
- Accept: text/plain, text/xml

Это наиболее правильный вариант с точки зрения HTTP, но для удобства я бы использовал 2й вариант (передача в URL).
Ответ написан
Комментировать
EvilsInterrupt
@EvilsInterrupt
System programming, Reversing Engineering, C++
Я бы предпочел второй способ. Указывание типа ответа вполне логично. Явное лучше чем неявное.
Еще Вы можете без параметров, а прямо в endpoint-е от URI:

На псевдо-питоне:
@app.route('employes/<uiid:string>/format/<type:string>')
def get_empoyes(uuid, type):
   if type == 'json':
     pass
   elif type== 'xml':
     pass
   elif type == binary:
     pass
   else:
     abort(404)


Также отмечу, что ответ лучше всегда сопровождать с content-type. А то некоторые забывают и приходится писать детекторы формата ;(((

P.S.:
По выбору имен. Имя 'type' ни о чем не говорит. Тип чего? Ответа? А может тип служащего? Тип автомобиля на котором ездит служащий?

P.S. #2:
Рекомендую почитать статью-перевод на хабре "RESTful API для сервера – делаем правильно" и книгу, которую привели в конце части 2
Ответ написан
Комментировать
@CobaltTheTerrible
Копипастю код на Python
В принципе любой из двух ваших вариантов подходит и будет в духе REST. Это неоднократно обсуждалось.

Однако я бы хотел предложить вам рассмотреть третий вариант: использование расширений:
super-rest/employees.xml
super-rest/employees.json
super-rest/employees.bin

Вот мнение Роя Филдинга на тему type vs extension
Regardless, it is a fact that the distinction between path and query in the URI syntax has nothing to do with how a service is implemented or whether a given representation of a resource can be saved as a file. Likewise, the only relevant distinction between file extensions and query-based media-type indicators is that the latter are too long and far more likely to cause undesirable cache impacts (many general-purpose caches refuse to store responses that look like queries because, historically, they tend to have lower hit rates than simple paths). That's why I always prefer extensions.

Neither choice has anything to do with REST.
Ответ написан
Комментировать
Пригласить эксперта
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы