GET or POST? Action not destructive, a lot of parameters, no need to cache

Question

I am designing an API endpoint that runs a simulation, and returns the result.

• The specific simulation that is run depends on many parameters.
• There are no side effects. Nothing destructive (creating, updating, deleting) is happening.
• I don't desire to cache the parameters in the query string of the URL for the user to save, or click refresh.

Should this endpoint accept GET requests, or POST requests?

• The query string isn't big enough to hold all the parameters. And apparently you aren't supposed to send a payload along with GET requests.
• There are no destructive side effects (no side effects at all). So POST doesn't seem appropriate either.

What should I do?

Answer 1

Should this endpoint accept GET requests, or POST requests?

I've got some good news for you. REST doesn't care.

Riddle: how would you provide this service on a web site?

You'd probably have some landing page of general interest, and onto that page you would add a link "click here to try the simulator!" When the consumer followed that link, you would provide a representation of a form describing the parameters required for the simulation, with an identifier for an endpoint and an action. The consumer would submit the filled out form, dispatching to your endpoint a representation of the simulator parameters.

A hypermedia API works the same way; the client shouldn't need to know the endpoint, or what method to use. What it needs to know is how to obtain that information from the representation of the form.

If you have a hypermedia API, you can change endpoints, or switch back and forth between http methods, without requiring that the client be updated to match.

There are no destructive side effects (no side effects at all). So POST doesn't seem appropriate either.

I've got more good news for you. Using POST is fine. The current authority for using POST isn't stack overflow, but RFC-7231

The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics. For example, POST is used for the following functions (among others):

• Providing a block of data, such as the fields entered into an HTML form, to a data-handling process

Perfect. It's not cacheable, unless you explicitly make it so. It contains facilities for redirecting the user to a cacheable representation of the data, for cases when that makes sense.

What POST doesn't do is communicate to the browser, or the intermediary components, that it is safe to retry a lost message.

Here's what Fielding had to say about this in 2009

It isn’t RESTful to use POST for information retrieval when that information corresponds to a potential resource, because that usage prevents safe reusability and the network-effect of having a URI.

POST only becomes an issue when it is used in a situation for which some other method is ideally suited: e.g., retrieval of information that should be a representation of some resource (GET), complete replacement of a representation (PUT), or any of the other standardized methods that tell intermediaries something more valuable than “this may change something.” The other methods are more valuable to intermediaries because they say something about how failures can be automatically handled and how intermediate caches can optimize their behavior. POST does not have those characteristics, but that doesn’t mean we can live without it. POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.”

HTTP doesn't specify a method for safe operations that include a payload. It does specify an idempotent method that includes a payload; PUT. Using PUT is unusual in so far as it doesn't really align with the usual understanding of "Create" or "Update", but so long as you are careful about identifiers, I think that it is valid.

Fielding, writing in 2006:

PUT does not mean store. I must have repeated that a million times in webdav and related lists. HTTP defines the intended semantics of the communication -- the expectations of each party. The protocol does not define how either side fulfills those expectations, and it makes damn sure it doesn't prevent a server from having absolute authority over its own resources.

I understand this to mean:

• The server is not constrained to track the state of the resource as is; it can use an output representation, rather than an input representation
• The server is not constrained on what access to allow; the resource can be write only. Or getting the resource can provide its input representation again.
• The server is not constrained on the permanence of the change; "we successfully processed your request (but then immediately reverted the outcome)" is perfectly valid.

From RFC 7231:

A successful response only implies that the user agent's intent was achieved at the time of its processing by the origin server.

In addition, the definition of the 200 status code gives you some room

For the methods defined by this specification, the intended meaning of the payload can be summarized as:

• GET a representation of the target resource
• PUT, DELETE a representation of the status of the action;

So I think it's an option that may, upon detailed review, be more suitable to your particular circumstances than POST or GET.

Answer 2

First, this API endpoint should be refactored and simplified. HTTP request with a lot of parameters should be avoided, no matter it is a GET or POST or something else. Request with a lot of parameters means very tight coupling between 2 modules -- client side have to assemble very carefully to meet the requirement of server. Also, request with a lot of parameters brings cost on documentation and training.

That said, it has to be a POST if a lot of parameters cannot be avoided. The reason is: although it should be a GET (semantically), GET is not feasible in this situation -- the request with all parameters exceeds the maximum limit of query string. Browser may truncate the query string and break the request.

In summary, it is not a question about what I should do, it is a question about what I have to do, unless the API endpoint is optimized.

Answer 3

I believe with something like this you would want to have aPOST request and return the user something in the Response in JSON or XML. Im using an API for a site now that sends a POST and I get the data out of the Response, and I to have a lot of parameters I'm passing.