Advanced Search REST API

[Akshai Srinivasan]

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-results?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 :)

[Andrew B]

You may find OData http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ inspiring.

[Neil Brewster]

A couple of others you might consider:

• RQL - http://www.persvr.org/rql/
  
• StrongLoop Loopback REST API - https://docs.strongloop.com/display/public/LB/Querying+data
  

There are also discussions at https://groups.google.com/forum/#!forum/json-query, but they seem to have died out years ago.

We chose to use Loopback on a recent project, using https://github.com/ljharb/qs to parse the query parameters and https://github.com/strongloop/loopback-filters to implement the actual filtering.

neil.

[Przemek Wesołek]

W dniu poniedziałek, 25 stycznia 2016 17:39:56 UTC+1 użytkownik Akshai Srinivasan napisał:

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-results?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?

If you have complicated searches, you may consider turning the search process and results into a resource on its own. Then searching would look something like:

--> POST http://myservice/api/v1/phones/search-process
--> (the body with search options, probably using one of standards proposed in other responses

<-- 201 Created
<-- Location: http://myservice/api/v1/phones/search-proces/some-id-of-the-process

and under the returned location there is a search process resource, which might have results. That way you also has the option to perform long searches (e.g. by returning "202 Accepted" instead and having application-dependent status in the body), query results incrementally (paging) or reuse existing search results (the same POST bodies returning the same location of the resource, probably with 3xx status code).

Przemek