如何为出口端点设计REST API? [英] How to design REST API for export endpoint?

问题描述

我正在设计REST API，并且遇到了设计问题.我有 alerts ，我希望用户能够 export 到几种文件格式之一.因此，我们已经开始使用 export 来执行操作/命令，感觉就像是RPC，而不是REST.

I am designing a REST API and am running into a design issue. I have alerts that I'd like the user to be able to export to one of a handful of file formats. So we're already getting into actions/commands with export, which feels like RPC and not REST.

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

Moreover, I don't want to assume a default file format. Instead, I'd like to require it to be provided. I don't know how to design the API to do that, and I also don't know what response code to return if the required parameter isn't provided.

这是我的第一个建议:

POST/api/alerts/export?format = csv

OR

POST/api/alerts/export/csv

此端点是否按照您的方式进行设置?是否以正确的方式设置了要求的文件格式?如果未提供所需的文件格式，则返回的正确状态码是什么?

Is this endpoint set up the way you would? And is it set up in the right way to require the file format? And if the required file format isn't provided, what's the correct status code to return?

谢谢.

推荐答案

实际上，您应该考虑使用HTTP内容协商(或CONNEG).这利用了 Accept 标头(请参阅HTTP规范:

In fact you should consider HTTP content negotiation (or CONNEG) to do this. This leverages the Accept header (see the HTTP specification: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1) that specifies which is the expected media type for the response.

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

For example, for CSV, you could have something like that:

GET /api/alerts
Accept: text/csv

如果要指定其他提示(文件名，...)，服务器可以返回 Content-Disposition 标头(请参阅HTTP规范:

If you want to specify additional hints (file name, ...), the server could return the Content-Disposition header (see the HTTP specification: http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1) in the response, as described below:

GET /api/alerts
Accept: text/csv

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

(...)

希望它对您有帮助，蒂埃里

Hope it helps you, Thierry

这篇关于如何为出口端点设计REST API?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！