How to design a REST API with LIKE criteria?

Question

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.

Answer 1

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.