API URL Structure [closed]

Question

I'm creating a sweepstakes application that is powered by an API. The hierarchy is fairly straightforward.

1. Clients
2. Users
3. Sweepstakes
4. Submissions

Clients can have users who are essentially admins of any sweepstakes. Clients can also have multiple sweepstakes. And a single sweepstakes can have multiple submissions. Okay, not complicated.

Where I get confused is what the correct approach is towards the URL structure. I've read documentation and best practice blogs all over the internet, and yet I'm still confused. Here are our current routes:

CLIENTS

POST /clients
GET /clients
GET /clients/:client_id
PUT /clients:client_id

USERS

POST /users
GET /users
GET /users/:user_id
PUT /users/:user_id
DELETE /users/:user_id

SWEEPSTAKES

POST /sweepstakes
GET /sweepstakes
GET /sweepstakes/:sweepstakes_id
PUT /sweepstakes/:sweepstakes_id
DELETE /sweepstakes/:sweepstakes_id

SUBMISSIONS

POST /submissions
GET /submissions
GET /submissions/:submission_id
PUT /submissions/:submission_id
DELETE /submissions/:submission_id

As you can see, I'm following a simple 2 URLs per resource -- what I feel is best practice. You can then drill into associations via query parameters on any GET request (e.g. /submissions?sweepstakes_id={sweepstakes_id}, /sweepstakes?client_id={client_id}, etc.).

This of course makes sense to me, however my co-worker and I are in a tiff because he is using Backbone to build the primary front-end app. Backbone states that they support RESTful API consumption off the bat, but my co-worker is telling me that Backbone prefers a URL structure that represents that hierarchal structure. I of course think that will leads to a messy, long, and overall confusing URL structure. Ideally, my co-worker would like to see the following URL structures:

GET /clients
GET /clients/users
GET /clients/sweepstakes
GET /clients/sweepstakes/submissions

Note: the above routes would also have additional routes to compliment single resources via an additional resource id in the URL (e.g. /clients/users/:user_id, /clients/sweepstakes/:sweepstakes_id/submissions, etc.).

I know this is somewhat of a touchy subject, but I'd love to hear some feedback on this. I vote for one 2 URLs per resource, and if any associations need to be made, they can be done so through the use of GET, or POST parameters. But I could be totally wrong.

Answer 1

You're right, this is a controversial topic. That being said I've found the gang at Apigee to be very helpful when trying to flesh out api standards/definition. They do not say that one way is correct, they more lean towards educated recommendations based off of their industry experience.

They offer some great resources and have some content that may help you get to a position where you can defend your opinion with someone else in your corner.

Check out this webinar... it is fairly basic stuff but always great for a refresher when it comes to api design.

note: I have no affiliation with Apigee, I just think that they have done some great work trying to get a standard defined for api design.

~ good luck and I hope this helps

Answer 2

I can't find anything in the official definition of REST that suggests that hierarchical URIs are preferred, but I may have missed something. I don't know anything about Backbone, but if it needs that structure I guess you have to do it, but there does not appear to be any reason why it would be better outside of that. However it is often preferred that each resource have one unique URI and the hierarchical one appears to have several. I know that you can't speak for your workmate, but has he offered any tangible reason why his scheme would have better functionality?