Appropriate REST design for data export

Question

What's the most appropriate way in REST to export something as PDF or other document type?

The next example explains my problem:

I have a resource called Banana. I created all the canonical CRUD rest endpoint for that resource (i.e. GET /bananas; GET /bananas/{id}; POST /bananas/{id}; ...) Now I need to create an endpoint which downloads a file (PDF, CSV, ..) which contains the representation of all the bananas.

First thing that came to my mind is GET /bananas/export, but in pure rest using verbs in url should not be allowed. Using a more appropriate httpMethod might be cool, something like EXPORT /bananas, but unfortunately this is not (yet?) possible.

Finally I thought about using the Accept header on the same GET /bananas endpoint, which based on the different media type (application/json, application/pdf, ..) returns the corresponding representation of the data (json, pdf, ..), but I'm not sure if I am misusing the Accept header in this way.

Any ideas?

VoiceOfUnreason · Accepted Answer · 2022-10-01 01:47:15Z

in pure rest using verbs in url should not be allowed.

REST doesn't care what spelling conventions you use in your resource identifiers.

Example: https://www.merriam-webster.com/dictionary/post

Even though "post" is a verb (and worse, an HTTP method token!) that URI works just like every other resource identifier on the web.

The more interesting question, from a REST perspective, is whether the identifier should be the same that is used in some other context, or different.

REST cares a lot about caching (that's important to making the web "web scale"). In HTTP, caching is primarily about re-using prior responses. The basic (but incomplete) idea being that we may be able to re-use a response that shares the same target URI.

HTTP also has built into it a general purpose mechanism for invalidating stored responses that is also focused on the target URI.

So here's one part of the riddle you need to think about: when someone sends a POST request to /bananas, should caches throw away the prior responses with the PDF representations?

If the answer is "no", then you need a different target URI. That can be anything that makes sense to you. /pdfs/bananas for example. (How many common path segments are used in the identifiers depends on how much convenience you will realize from relative references and dot segments.)

If the answer is "yes", then you may want to lean into using content negotiation.

In some cases, the answer might be "both" -- which is to say, to have multiple resources (each with its own identifier) that return the same representations.
That's a normal thing to do; we even have a mechanism for describing which resource is "preferred" (see RFC 6596).

Rob Conklin · Accepted Answer · 2022-09-30 15:16:39Z

Media types are the best way to represent this, but there is a practical aspect of this in that people will browse a rest API using root nouns... I'd put some record-count limits on it, maybe GET /bananas/export/100 to get the first 100, and GET /bananas/export/all if they really want all of them.

inf3rno · Accepted Answer · 2022-11-04 01:48:18Z

REST does not care about this, but the HTTP standard does. Using the accept header for the expected MIME type is the standard way of doing this, so you did the right thing. No need to move it to a separate endpoint if the data is the same just the format is different.

Collectives™ on Stack Overflow

Appropriate REST design for data export

3 Answers 3

Comments

Comments

Comments

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

Comments

Comments

Comments

Related