Performing searches in a RESTful fashion

[Grant Sheppard]

Hi everyone,

I'm developing a web application which will be used to search for
products stored in a backend database. I've put together a product
search service that isn't RESTful in any respect. I simply perform a
POST, passing across some product search criteria and receive the
product results in the response.

Ideally I'd like to follow proper RESTful principles. The method which
I'm currently considering is as follows: -

1) The client performs a HTTP POST with the search criteria. This will
create a new 'search results' resource on the server side. The HTTP
response will contain the URI for this new results resource.
2) The client then performs a HTTP GET to retrieve the results using
the URI provided in the initial response.

Although this is workable I'm not happy with the fact that this
requires two full round trips to perform a search. Can anyone suggest
a better approach that still adheres to the principles of RESTful and
ideally sits at level 3 in the Richardson Maturity Model?

Kind Regards,

Grant Sheppard

[JBJ]

Hi Grant,

There could be two approaches to this, in my opinion. The first could be that you've already got a suitable resource that represents all products that you want to search. A GET request with URL parameters indicating the filtering you want to apply would allow the search criteria to be passed through the GET request and limit the values being returned. I've often used the OpenSocial specifications as a source of inspiration in the past so have a look at their Collection Request Parameters. The other bit of OpenSocial/OpenSearch I've used in the past is I like the startIndex, itemsPerPage and totalResults fields when serving back paged sets of data. 

The alternative would be more like your workaround. OpenSearch defines a POST-able query with search criteria where the response contains the results. This would save you the need to do a subsequent GET provided your results are returnable in a timely fashion. However it would involve creating a search resource which might not feel as pure as modelling separate search features per resource but you'll know what kind of searching you want to support. 

Your point about adhering to Level 3 of RMM is down to the implementation. You could indicate that a resource is searchable by adopting the OpenSearch suggestion of adding link elements that have a suggested format of something like

<link rel="search"
           type="application/opensearchdescription+xml" 
           href="http://example.com/content-search.xml"
           title="Content search" />

This would allow those clients wanting to search to know how to navigate to an end point that supports queries. Whether you provide a central search point or searching per resource is up to you. I've not implemented this in any live service yet but thought I'd mention it in case it was of use. 

Hope any of this is food for thought and useful

Cheers,

Jonathan

[Grant Sheppard]

Thanks for the prompt reply, Jonathon.

The first approach doesn't really appeal to me because it means that you effectively do away with 'clean' URI's which affects the ability of intermediate servers (proxies, etc) to cache requests. Your second approach is something that I'll definitely investigate further though. I've not heard of OpenSearch before so there should be some good bedtime reading there for me :-)

Thanks again,

Grant

[Jim Webber]

What about POST-redirect-GET for this? The resource created as a side-effect of POST is probably quite cacheable for any other POSTs that redirect to the same URI.

Jim