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

Question

[Максим]

Пилю 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 как то по разному об этом сказано..

Comments

[Yaroslav Lyzlov]

Зачем указывать в url это? Первый вариант оптимальный.

[Максим]

Yaroslav Lyzlov: т.е. с точки зрения http это корректно - указывать тип будущего ответа?

[Yaroslav Lyzlov]

Конечно. Лучше сказать "тип ожидаемого ответа"

[Максим]

Ок, благодарю.

Answer 1

[D']

Так есть же специальный заголовок Accept, в котором клиент указывает какие форматы он поддерживает.
Т.е:
- Accept: application/json
- Accept: text/xml
- Accept: text/plain, text/xml

Это наиболее правильный вариант с точки зрения HTTP, но для удобства я бы использовал 2й вариант (передача в URL).

Answer 2

[Дмитрий]

Я бы предпочел второй способ. Указывание типа ответа вполне логично. Явное лучше чем неявное.
Еще Вы можете без параметров, а прямо в 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

Answer 3

[Кобальт Грозный]

В принципе любой из двух ваших вариантов подходит и будет в духе 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.