rest - 如何为导出端点设计REST API？

Question

我正在设计REST API，并且遇到了一个设计问题。我有alerts，希望用户能够将export转换为少数几种文件格式之一。因此，我们已经开始使用export来执行 Action /命令，它就像RPC而不是REST。

而且，我不想采用默认的文件格式。相反，我想要求提供它。我不知道如何设计API来做到这一点，而且我也不知道如果没有提供必需的参数，该返回什么响应代码。

因此，这是我的第一个建议:
POST /api/alerts/export?format=csv
或者
POST /api/alerts/export/csv
该端点是否按照您的方式进行设置？是否以正确的方式设置了要求的文件格式？如果未提供所需的文件格式，则返回的正确状态码是什么？

谢谢。

Answer 1

实际上，您应该考虑使用HTTP内容协商(或CONNEG)来进行此操作。这利用了Accept header (请参阅HTTP规范:http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1)，该 header 指定了响应的预期媒体类型。

例如，对于CSV，您可能会有类似的内容:

GET /api/alerts
Accept: text/csv

如果要指定其他提示(文件名，...)，则服务器可以在响应中返回Content-Disposition header (请参见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" 

(...)

希望对您有帮助，
蒂埃里