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

Question

我正在设计REST API并遇到设计问题.我有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" 

(...)

希望它对你有帮助,蒂埃里