如何为导出端点设计REST？

Question

我正在设计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" 

(...)

希望它能帮到你，蒂埃里