CODEWITHSUNDEEP
resthttpuriweb-standards
Paul Rodgers
Paul Rodgers

Reputation: 1

RESTful API for filtering by two models simultaneously

Suppose I have two models, Order and Customer. I've implemented an API that lets you filter on both:

/orders?status=fulfilled
/customers?city=Atlanta

But what if I want to search for orders in a fulfilled status, whose associated customer also lives in Atlanta? Is it RESTful to do something like /orders?status=fulfilled&customer.city=Atlanta? Or is there a canonical format for doing this sort of thing?

Upvotes: 0

Views: 333

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57377

Is it RESTful to do something like /orders?status=fulfilled&customer.city=Atlanta?

Yes.

is there a canonical format for doing this sort of thing?

No.

You will normally want to choose a resource identifier that is compatible with a standardized URI Template because that lets you leverage pre-existing libraries.

But there are a lot of different ways you can expand variables into a template.

A query part composed of application/x-www-form-urlencoded key value pairs is a common choice; it gives you compatibility with HTML forms "for free". But if you aren't expecting clients to interact with your API via web pages, maybe that's not too important.

URI spellings are a lot like spellings of variable names; the machines don't care. You, therefore, have extra degrees of freedom that you can use to make life easier for some people: your clients looking at identifiers in their browsing history, your operations people looking in logs, your technical writers trying to document the API....

You'll probably want to choose something that is convenient for yourself -- so make sure that your design fits well with your routing framework.

Choosing identifier spellings that direct these requests to the same controllers that you are already using vs. a new controller -- that's entirely up to you. Part of the point of the API is that the implementation details are hidden from the client and can be changed without breaking the interface.

Upvotes: 0

Related Questions