Htykuut

I have implemented an /GET HTTP endpoint to provide search feature. The user sends search terms in query parameters and receives JSON response containing all search results.

Now I have to add a new feature i.e. save search. It means the user sends same search parameters and can also send a boolean parameter say save=true. I have to save the search term in database in this case for future uses. However this parameter is not mandatory.

I am confused over the following points:

1. Modify same GET HTTP endpoint allowing additional save parameter in query parameters.


2. Modify same GET HTTP endpoint but passing save parameter in request body instead of query parameters as its backend state changing parameter.


3. Use separate endpoint for save the parameters using POST method.

What is the standard/acceptable way of doing this?

As far as I understood your question you try to store a search request and by storing it also retrieve the response in one go?

Usually GET is used to retrieve a resources' state though as this method is defined as safe it shouldn't be used if certain state is created for the invoked resource as persisting the search query would be. RFC 7231 further states that:

A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some existing implementations to reject the request.

I therefore would refrain from option #1 or #2 as this might break interoperability by certain clients.

POST on the otherhand is defined in RFC 7231 as

The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics.

It therefore should be used in every situation the other HTTP operations don't fit. The HTTP spec further defines that creating a new resource a 201 Created HTTP status code should be returned including a HTTP response header named Location containing the URI of the created resource. This URI can later be used to retrieve it's state (i.e. the performed search result).

From a client's perspective you are basically storing some query definition on the server and don't care where or how the server is actually persisting it. All you care is to retrieve a handle you can later on invoke. This doesn't prevent the server from returning the current search result within the response payload. And this is what I'd do exactly.

Proposed steps:

• Send search request via POST


• Store query definition


• Generate the URI for the stored query


• Perform the search according to the query


• Return a response with a 201 Created status code and Location header pointing to the URI of the stored query and add the query result within the response payload

A client can later on use the returned URI to retrieve the current state of the resource, which the server can interpret as: execute the query stored for that URI and return the search result.

How the URI has to look like is not defined by the REST architecture. You might generate UUIDs or generate a hash value based on the query generate. The latter approach has the benefit that multiple identical queries wouldn't result in additional queries created but in the reusage of such. In such cases a redirect to the existing query resource should be performed to tell the client that his query already existed which also teaches the client the actual URI of the query resource as a side effect.