CODEWITHSUNDEEP
web-servicesresthttp
David Jones
David Jones

Reputation: 10219

Which HTTP verb is appropriate for processing a file and returning a result?

I'm creating a REST API with an endpoint that takes a file as input (e.g. an Excel file), extracts all the email addresses from the file, and returns a list of email addresses. What would be the most appropriate HTTP verb to use for this endpoint? Semantically, it seems like a GET is the best choice, but passing file data in a URL seems like a bad idea. A POST would be better for passing a file, but POST implies a database record will be created and that the operation is not idempotent (which it is).

I realize this is a nit-picky semantics question, but surely others will have the same question, so hopefully the answer will be useful.

Upvotes: 10

Views: 1881

Answers (4)

Guillaume CR
Guillaume CR

Reputation: 3016

I think the key sentence in the PUT RFC is this:

A successful PUT of a given
representation would suggest that a subsequent GET on that same
target resource will result in an equivalent representation being
sent in a 200 (OK) response.

There is no such expectation in your use case scenario (unless users are expected to PUT to different url's for each different Excel and you save each response). It seems to fall well into the "data processing resource" described for POST in the same RFC.

Upvotes: 0

PaulProgrammer
PaulProgrammer

Reputation: 17630

The discussion is a bit pedantic, but my 2c is PUT. PUT is an idempotent verb, and implies that it will be operating only on the resource that is being PUT. However, RFC 2616 suggests that the server MUST send a 301 redirect to the result.

From RFC 2616

The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI,

it MUST send a 301 (Moved Permanently) response; the user agent MAY then make its own decision regarding whether or not to redirect the request.

Of course, as Julian pointed out so politely, RFC 2616 has been obsoleted by RFC 2731 which makes no such requirement.

YMMV. In reality, it seems to make sense to just do what makes sense to you.

Upvotes: 2

Julian Reschke
Julian Reschke

Reputation: 42025

POST doesn't imply idempotency, nor does it imply creating a DB record.

It's true that it would be nice not to have to use POST for something that is idempotent and save, but right now, there isn't a better HTTP method for that.

Upvotes: 3

0xeaea0000
0xeaea0000

Reputation: 106

Don't get hung up on this. It is the sort of thing that won't matter once make a decision. Personally I'd stick POST for anything that doesn't fall within "CRUD" semantics. Heck, if you were designing a SOAP or WCF service you probably wouldn't be considering this decision and that is one reason I don't place much importance on designing to the RESTful model unless there is a specific requirement to do so in order to interop. Otherwise, I design a SOA with service contracts that make sense, with no thought about which transport verb it falls under.

Upvotes: 0

Related Questions