CODEWITHSUNDEEP
jsonapirestrestful-architecture
nesh_s
nesh_s

Reputation: 399

REST Interface and Search

I am in the process of writing a REST API spec and struggling to find the correct representation for the search functionality.

The search would typically expect 1 or 2 main (non-optional) parameters along with 10-15 optional parameters (which may or may not be filters) and hit a solr/elasticsearch implementation to get content

I have read How to design RESTful search/filtering? and http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api and tempted to expose "search" itself as a resource and do a POST with a JSON body. However it doesn't feel right (and RESTful) when a more acceptable approach is query parameters and GET

The UI this API will feed into is actually a Search website. So a typical user scenario will be user searches for something and once a list is returned, the user is able to drill down to each element/item. The item will not be a flat object. It will be a complex object with nested resources which i intend to expose by following HATEOAS.

I am not entirely sure how to proceed with this and was hoping to get some feedback/answers.

Thanks very much

EDIT

I ended up doing what is suggested here by user Qwerty RESTful URL design for search

thanks you all those who commented.

Upvotes: 2

Views: 2188

Answers (1)

Opal
Opal

Reputation: 84786

I've faced a similar problem recently and:

  1. Simple GET can be used. The length of URL should not be an issue. You also mentioned that most of the query parameters are optional so you can simply give it a try.

  2. The solution we've applied. The assumption is you need to filter api/items/ based on given parameters. One thing that can be done is to introduce a new endpoint, namely: api/items/search/ but this is not RESTful - (BTW: IMO when REST rules are to be omitted this is the best case to do that).

    The idea is to introduce a api/filters/ endpoint which will be used to create (via POST) a filter with all the parameters that can be used to filter items. Then in response you can return 201 Created along with body and filterId of newly-created filter set. When you have this filterId make a request to api/items/filterId=<someId> and you'll receive the collection of filtered items.

    Second approach is to return 303 SeeOther along with Location header just from created filter. Your client library will take care of the whole communication and it will be transparent. This approach isn't truly RESTful, however you save a call and time.

    Filters can be persistent or given some TTL. You can also easily track search history.

EDIT

I was wrong when it comes to 303 and REST - see here.

Upvotes: 1

Related Questions