Должен ли я использовать заголовок accept http или более явный ресурс api rest, чтобы определить формат данных, запрашиваемый клиентом?

Question

Допустим, у меня есть такой API-интерфейс: /api/v1//modify?txtUri={a-text-file-uri-goes-here}, который фильтрует и модифицирует данный текстовый файл, расположенный по указанному URI, и возвращает в ответе полезной нагрузки отфильтрованный текстовый файл на основе некоторых внутренних бизнес-правил.

Сначала я хотел вернуть только JSON, но я хотел бы разрешить разные форматы возврата.

Лучше ли (то есть самым стандартным способом):

• использовать разные ресурсы:

  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}/json
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}/xml возвращает
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here} откат по умолчанию, возвращает JSON

• добавить еще один необязательный параметр строки запроса format:

  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}?format=json возврат в формате json
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}?format=xml возвращает формат xml
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here} откат по умолчанию, возврат возвращает json

• установить HTTP-заголовок Accept: https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/Accept с тем форматом возврата, который мы хотим получить, если он не установлен, то мы возвращаем http-код 406.

Answer 1

Используйте заголовок Accept, поскольку REST API - это HTTP, и именно так работает HTTP. Это также то, что ожидают пользователи вашего API.

Определенно не используйте QueryString, если вы не хотите использовать заголовок accept - вы можете использовать расширение одним нажатием, например. /api/v1/modify.json?txtUri= enja-text-file-uri-goes-here} Твиттер это делает, но я бы предпочел заголовок Accept.