0

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

or

baseURl/api/v1/resource?format=xlsx

Thank you in advance.

Luis Carlos Cruz Castillo
  • 160
  • 10
  • Questions that command answers opinion-based in nature are explicitly off-topic per the scope of the site defined in the [help/on-topic] – esqew Feb 03 '22 at 22:30

2 Answers2

1

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 ....

VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
0

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)

Dijkgraaf
  • 11,049
  • 17
  • 42
  • 54
cWerning
  • 583
  • 1
  • 5
  • 15
  • 1
    My question is not about the header, is about the endpoint, path variable or query parameters – Luis Carlos Cruz Castillo Feb 03 '22 at 22:41
  • Luis isn't talking about the response header, not even about the information returned on the endpoint, as my understanding, he's asking for best practices for an endpoint resolution. – Miguel V Feb 03 '22 at 22:43
  • 1
    @MiguelV He isn't talking about response headers, he is talking about client headers. So rather than specifying the type in the URL, the client does it in the headers. – Dijkgraaf Feb 03 '22 at 23:35
  • @luiscarloscruzcastillo yes I'm talking about client headers. You shouldn't be putting the format in the path or query parameters. This should be specified in the headers using the `Accept` key and value. – cWerning Feb 04 '22 at 02:48