What should I use as an endpoint to serve downloadable documents using REST API?-CodePudding

Right now I have an endpoint that servers a file to the user (json, csv, excel or pdf).

My question here is, which type of route should I use to serve it, path variables or query parameters (considering best practices and for developer comprehension):

baseURl/api/v1/resource/xlsx

baseURl/api/v1/resource?format=xlsx

Thank you in advance.

CodePudding user response：

It is best practice to use headers for HTTP to show what format the client can understand. You should use a get route and include the Accept header for the format.

Header key: Accept

Header Value: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept

HTML Input="file" Accept Attribute File Type (CSV)

CodePudding user response：

So long as you are consistent with the production rules of the http URI scheme, any spelling conventions you choose are fine.

Choosing spellings that match the capabilities of URI templates will make it easier to construct/deconstruct resource identifiers in a "common URI space", which is often convenient both for clients and servers.

Using path segments vs query is purely trade offs. Using application/x-www-form-urlencoded key value pairs in the query part mean that you can implement your URI template as an HTML form. Using path segments means that you can use dot segments to describe other identifiers in the common URI space.

If you don't care about either of those, it just comes down to which spellings you like best in an access log, or in your documents, or in a browser history, or when you paste them into an email message, or ....