views:

84

answers:

3

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.

A: 

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 :)

k_b
Yeah, I was thinking about doing this way, it seems like a lot more coding though. We're using Google Big Table, probably don't have to worry too much about SQL injections in this case.
DutrowLLC
You could always make something generic out of looking for prefixes like for instance min_ and max_, followed by an exact attribute, building queries automatically. In the same way, you'd split the 'sort' query parameter on the commas, and then check whether .desc or .asc are present as a suffix. Implement this query building logic once, and you could use it for all resources.
k_b
+1  A: 

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.

CodeToGlory
What would be the advantages of making search a first class resource?
DutrowLLC
+1  A: 

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

manuel aldana
I like it, it looks really clean. The only thing I can think of that might cause problems is if one of the search parameters like "age" conflicts with another command. For example, what about the (unlikely) event that "sortField" was also a column in the table that you could search by?
DutrowLLC
from security point of view you anyway shouldn't directly propagate outside parameters directly to the backend (injection attacks). you should create a little 'mapping-layer', where the http parameters are checked, filtered and mapped to the "real" backend-query command.
manuel aldana