CODEWITHSUNDEEP
apirestrestful-architectureconventions
nak
nak

Reputation: 936

Deciding on REST API Path Convention

I am working for classified section of my organization where I need to fetch cities available for this section. Classified cities are the subset of the cities. So, for fetching the cities I created the following API path. 

api/classified/cities

Then I realize since the classified cities are the subset of cities the URL can be 

api/cities/classifiedcities

which one of the above path should I use according to REST principals?

Upvotes: 2

Views: 249

Answers (2)

Robert Bräutigam
Robert Bräutigam

Reputation: 7744

If you are aiming for REST principles, REST does not really have any principles how a URI might look like (as long as it identifies a "real" resource!). It does however say that it should be linked instead of hardcoded into the clients. This is why some people say URIs do not matter. They do not matter because clients should "discover" URIs instead of knowing them beforehand.

So why don't we all pick URIs like "/45ttfdfg/34tkfjdldf23wedkdfjsd"? That, again is up to personal preference really. It is nice if the URI is "readable" by humans. There are some (badly written) tools that assume some structure. There are some "REST" libraries (server and client ones) that also assume a bunch of stuff, for example the concept of "subresources" (which also does not come from REST).

To sum up: If you follow REST (you don't have to of course!), then clients should discover URIs. If that is the case, then it comes down to personal preference and maybe some technical restrictions with libraries/clients. So pick one which you prefer, don't worry about it! They can be modified later if needed anyway, since the server has control over its URIs.

Upvotes: 2

Alex Marculescu
Alex Marculescu

Reputation: 5770

Theoretically the subset should follow the parent set (so the first solution doesn't look too good).

One third approach would be through query parameters:

api/cities?type=classified

Upvotes: 1

Related Questions