What are the RESTful best practices on defining a query parameter with an or condition?

Question

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

/people?q="[email protected]||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

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.