How to obtain REST resource with different finder “methods”?

StackOverflow https://stackoverflow.com/questions/1622085

  •  06-07-2019
  •  | 
  •  

Question

Let's say you had a /companies resource that allowed clients to lookup public companies and you wanted clients to be able to lookup companies by Ticker, Location, and Location and industry

Would you keep the same URL in the form:

  • GET /companies/msft
  • GET /companies/usa
  • GET /companies/usa&software

This doesn't seem right. Any ideas?

Was it helpful?

Solution

How about?

GET /Companies?ticker=MSFT

GET /Companies?country=USA

GET /Companies?country=USA&industry=software

The important thing is to identify the resource. The resource is "a list of Companies". Its media type could be an Atom list, or just an HTML document using UL LI tags. The query parameters affect the contents of the list, but conceptually, it is still "a list of companies".

You could create a distinct resource such as 

GET /Companies/USA

but do you really need to. Are you going to POST to /Companies/USA? Are you going to delete /Companies/USA? If your application does not require the ability to perform additional operations on these specific sets of companies then why bother modeling them as distinct resources?

As a side note to this discussion, I like to distinguish more clearly when I am accessing a resource which is a single entity versus a list. i.e.

GET /Companies/USA

GET /Company/MSFT

I realize this is not the way some of the popular web frameworks work, but I have found it a useful distinction.

OTHER TIPS

You could accept any of those, but then return a Location: header pointing to the canonical address (presumably GET /companies/msft).

You have only one company, but multiple ways of getting to it, so I'd probably define /companies/[unique-name], and then various things like /companies/byticker/msft and /companies/bylocation/usa etc.

Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow
scroll top