Advanced search REST API

Question

My requirement is to implement advanced search Rest API for searching the phones. The URI for the search API is http://myservice/api/v1/phones/search?q=${query_expression}

Where q is the complex query expression. Have the following questions

1) Since advanced search involves a lengthy query expression, the URI will not fit in a GET call. Is it alright to implement the search API via POST request and still maintain the RESTfulness?

2) I have come across the following implementations for the advanced search:

• 1st approach - Send the complete infix expression for the query expression. eg.

PHONENAME STARTSWITH 'AR' AND ( PHONETYPE = '4G' OR PHONECOLOR = 'RED')

• 2nd approach - Constructing entire query expression in the form of a json. eg.

  {"criteria":[ {"index":1,"field":"PHONENAME","value":"AR","comparator":"STARTSWITH"}, {"index":2,"field":"PHONETYPE","value":"4G","comparator":"EQUALS"}, {"index":3,"field":"PHONECOLOR","value":"RED","comparator":"EQUALS"} ],"criteria":"( 1 AND (2 OR 3) )"}

• 3rd approach - Alternative way to implement the query expression as a json. eg.

  {"and":[ {"field":"PHONENAME","value":"AR","comparator":"STARTSWITH"}, "or":[ {"field":"PHONETYPE","value":"4G","comparator":"EQUALS"}, {"field":"PHONECOLOR","value":"RED","comparator":"EQUALS"}] ]}

Which approach would be considered more RESTful out of the three? Suggestions for any other approaches are welcome :)

Answer 1

1. Yes, POST is a catch-all. It's preferable to use it for resource creation, but according to the spec it may be used in this way also. However, you should consider changing the endpoint to be /search-results. This gives you the flexibility to start storing search results later, and you can return a Location header pointing to the results of a particular complex query. Another alternative is to let users POST their search criteria, and then do a GET /search-results?criteria={id}.

2. Don't do the second one. It's hard to read and more complex than it should be. Either the first or the third are fine. The first is more compact but probably harder to handle on the back end. For the third, you really don't need the index.

Answer 2

You could follow the approach taken by ElasticSearch, which out of the examples you had given is the third one.

See https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html

The third approach is also easier to understand and easier to maintain. For example if in the future you would need to add "fuzzy" query operator and it would have a completely different model, that would be an easy thing to do.