What are the RESTful best practices on defining a

Question

I would like to know, following RESTful best practices in which ways should I define an url like the following:

/people?q="email=[e-mail]||phone=11111"

The point would be to search for a person either by their email address or phone depending on what they've inserted on a search box.

I've been reading a few guides on best practices in using RESTful services but none seem to talk about this situation.

Answer 1

An alternative might be:

/people?or_email=[e-mail]&or_phone=11111

This way you could also implement searching by mail and phone

/people?and_email=[e-mail]&and_phone=11111

or even do more complex queries like:

/people?and_email=[e-mail]&and_phone=11111&or_name=Alice

Answer 2

REST means you follow standards by building the (uniform) application interface.

Currently there is no standard solution for general querying with GET. There are many non standard URL query languages you could use. E.g. RQL, OData, most of the structure of database REST API URIs: e.g. mongodb, etc... So try not to reinvent the wheel. As an alternative you can send a serialized query in a query param as you did in your example. It can be on any standard query language, e.g. SPARQL if you use REST with RDF vocabs like hydra. If you don't then you have to describe it in the documentation of your vendor MIME type. (General querying means in this context that you don't know what the structure of the query will be.)

If you are looking for a non-general querying solution, then you can use any URI template as long as you describe somehow the parameters of your link with your RDF vocab or in the documentation of your vendor MIME type. If you don't understand what I am talking about, check the uniform interface constraint / self-descriptive message, HATEOAS sections of the manual or use wikipedia. (Non-general querying means in this context that you have an idea about what the query structure will be and you can describe it with URI templates.)

Be aware that you have to parse and validate and authorize these queries, so sending an SQL statement and running it through the database without any check can be fatal to your application.

Answer 3

How about:

/people?condition=OR&email=[e-mail]&phone=11111

This would allow for refinements to the query method without changing the name/URL of the endpoint.