Как создать REST API для конечной точки экспорта?

Question

Я разрабатываю API REST и сталкиваюсь с проблемой дизайна. У меня есть alerts, что я хотел бы, чтобы пользователь мог использовать export в одном из нескольких форматов файлов. Таким образом, мы уже вступаем в действия/команды с export, который чувствует себя как RPC, а не REST.

Кроме того, я не хочу принимать формат файла по умолчанию. Вместо этого я хотел бы потребовать его предоставления. Я не знаю, как создать API для этого, и я также не знаю, какой код ответа будет возвращен, если требуемый параметр не указан.

Так вот моя первая трещина на него:

POST /api/alerts/export?format=csv

ИЛИ

POST /api/alerts/export/csv

Настроен ли это конечная точка так, как вы бы? И правильно ли он настроен на формат файла? И если требуемый формат файла не указан, каков правильный код состояния для возврата?

Спасибо.

Answer 1

На самом деле вы должны обсудить согласование содержимого HTTP (или CONNEG) для этого. Это использует заголовок Accept (см. Спецификацию HTTP: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1), которая указывает, какой тип ожидаемого медиа для ответа.

Например, для CSV, вы могли бы иметь что-то вроде этого:

GET /api/alerts 
Accept: text/csv 

Если вы хотите, чтобы указать дополнительные подсказки (имя файла, ...), сервер может вернуть заголовок Content-Disposition (см спецификация HTTP: http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1) в ответ, как описано ниже:

GET /api/alerts 
Accept: text/csv 

HTTP/1.1 200 OK 
Content-Disposition: attachment; filename="alerts.csv" 

(...) 

Надеется, что это помогает вам, Тьерри