4

I'm building a REST API endpoint that creates an Excel file export and I'm wondering if this should be a GET or POST request. I can think of several reasons to do either.

In general I'd use GET for fetching data and POST for creation, but this seems to be a bit of a grey area.

This endpoint will be called from JS on button click so there is no limitation there for either one or the other.

Reasons to use GET:

  • The file is not stored anywhere, so no state is updated on the server.
  • The endpoint could be bookmarked (although it's not a requirement).

Reasons to use POST:

  • Technically something gets created, so the action is not idempotent even though nothing is saved.
  • In the future complex filters might be added which could get complex if these have to be added in the query string.
  • The response might change on consecutive requests so it cannot be cached.

What's the recommended HTTP request method in this scenario?

Duncan Lukkenaer
  • 12,050
  • 13
  • 64
  • 97
  • 1
    this might be worth a read where it says filtering is really creating a search object https://stackoverflow.com/questions/5020704/how-to-design-restful-search-filtering – codebrane Aug 10 '20 at 14:49

1 Answers1

3

What's the recommended HTTP request method in this scenario?

If the request is essentially read only, then you should use GET.

The response might change on consecutive requests so it cannot be cached.

That matters less than you might expect, because the server controls the caching metadata. So if you want the client to ask for a fresh copy every time, you just tune the headers appropriately.

The fact that the response isn't cacheable doesn't change the semantics of the request.

In the future complex filters might be added which could get complex if these have to be added in the query string.

Practical answer: worry about that when you get there.

Yes, if you give the client code enough options, it will eventually become impractical to capture all of those options in the target-uri; at that point, you may need to change to a protocol that communicates the options in the request-body, at which point you'll need to give up on GET as the method-token that communicates those options to the server.

VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91