CODEWITHSUNDEEP
apirest
colethecoder
colethecoder

Reputation: 1149

How to design a REST API with LIKE criteria?

I'm designing a REST API and have an entity for "people":

GET http://localhost/api/people

Returns a list of all the people in the system

GET http://localhost/api/people/1

Returns the person with id 1.

GET http://localhost/api/people?forename=john&surname=smith

Returns all the people with matching forenames and surnames but I have a further requirement. What is the cleanest / best practice way of allowing API consumers to retrieve all the people whose forename starts with "jo" for example.

I've seen some APIs do this like:

GET http://localhost/api/people?forename=jo~&surname=smith

where the tilde signifies a "fuzzy" match. On the other hand I've seen it implemented with a totally different criteria e.g.

GET http://localhost/api/people?forename-startswith=jo&surname=smith

which seems a bit cumbersome considering I might have -endswith, -contains, -soundslike (for some sort of soundex match).

Can anyone suggest from experience which works better and also any examples of well designed REST APIs that have similar functionality.

Upvotes: 8

Views: 17012

Answers (4)

Vikram
Vikram

Reputation: 4190

IMHO it does not matter if you have fuzzy matches or have -endswith -contains etc. What matters is if your REST API permits easy parsing of such parameters so that you can define functions to fetch data from your data source (DB or xml file etc.) accordingly

If you are using PHP...from my experience, SlimFramework is a great light weight, easy-to-get-started solution.

Upvotes: 4

Aliostad
Aliostad

Reputation: 81660

AFAIK, none of above are quite RESTful. Both of them rely on a priory knowledge on the client's part on how to invoke queries (in the first case, query pattern and on the second one a query DSL). In the second example, in fact, the API is reduced mere to a wrapper around the data store. As such, API does not define a server domain - it is a data provider. This is in contrast to the client-server constraint of REST.

If you need to expose a full-blown data store with all various querying capabilities, you had better stick to known standards which we have OData. OData has been sold as REST but many REST-heads have problems with it. Anyhow, at the end of the day it works and REST discussions can commonly lead to analysis-paralysis.

If I was doing this, I would probably constraint the API to a common use-case, so something more like the second one without defining a query DSL (hence forenameStartsWith rather than forename-startswith).

Having said that, if you need to query based on many fields and various conditions, I would use OData.

Upvotes: 2

William Durand
William Durand

Reputation: 5519

I would recommend you the OData protocol which provides a Query String Options. What you did is ok and follows REST conventions.

But, the OData protocol describes a $expand parameter and even a $filter parameter. This $ prefix denotes "System Query Options" and you will be interested in the last one because it allows you to write the following URI:

http://services.odata.org/Northwind/Northwind.svc/Customers?$filter=tolower(CompanyName) eq 'foobar' &select=FirstName,LastName&$orderby=Name desc

It allows you to pass SQL like data, it can be a nice alternative to what you described (both solutions are fine, it's just a matter of taste).

Upvotes: 3

user647772
user647772

Reputation:

Both examples use query parameters for filtering. I don't think it matters what these query parameters are called or if some wildcard syntax is used.

Both approaches are equally RESTFul.

Upvotes: 0

Related Questions