REST/ROA Architecture - Send database search/querying/filter/sorting parameters in URL? (>, <, IN, etc...)

Question

I'm building a REST interface to my application using ROA (Resource Oriented Architecture).

I'd like to give the client the ability to specify search parameters in URL. So a client could say "Give me all people who's:

• "first_name" is equal to "BOB"
• "age" is greater than "30"
• sort by "last_name"

I was thinking something like:

GET /PEOPLE/{query_parameters}/{sort_parameters}

...or perhaps

GET /PEOPLE?query=<query_string>&sort=<sort_string>

...but I'm unsure what syntax would be good for specifying in the COLUMN_NAME-OPERATOR-VALUE triplicates. I was thinking perhaps something like:

column_name.operator.value

So the client could say:

GET /PEOPLE?query=first_name.EQUALS.bob&query=age.GREATER_THAN.30&sort=last_name.ASCENDING

I really don't want to re-invent the wheel here, are there some accepted ways that this is done? I am using Restlets, I don't know if that makes a difference.

Answer 1

I'd go for something like this:

GET /PEOPLE?first_name=bob&min_age=30&sort=last_name.asc,age.desc

And, watch out for SQL injections :)

Answer 2

Why don't you think on the lines of making search a first-class resource? See below, you can specify an objectType in searchQuery to indicate you are searching the People resource.

/search/{searchQuery}

For example, the below query indicates a search on all people between the age 30 and 50.

/search?objectType=People&ageField1=30&ageField2=50&inclusive=true

You can do similar things with sort as well.

Answer 3

i would add the search parameters as single parameters. a dedicated sub-query language is often more difficult to handle+read (especially because you have to url-encode it). so I wouldn't squash a full feature blown sql syntax one. Only add parameters you really need and make sense to the search, less complexity can mean easier handling :)

min/max stuff I would add to the same parameter. /people?age=10,20

Note the ',', it implicitly offers you a range syntax. I find it more readable as having minAge and maxAge.

for an open range you could do: /people?age=10,*

the sorting i would do: /people?sortField=name&sortOrder=ascending