CODEWITHSUNDEEP
djangorestapidjango-rest-framework
Light1988
Light1988

Reputation: 77

API RESTful Resource Naming

I always have the doubt that you can see below when i need to create theresource URLs for a REST API. I wonder if some one can help me.

Let's suppose that i have two models.

User can submit his own posts and can comment his own and another posts.

Main resources URLs for User would be:

GET  /users                     # Retrieve all users.
POST /users                     # Create a new user.
GET/DELETE/PUT /users/{user_id} # Get, remove and update an user.

Main resource URLs for Post would be:

GET  /posts                     # Retrieve all posts.
POST /posts                     # Create a new post.
GET/DELETE/PUT /posts/{post_id} # Get, remove and update a post.

My problem come when for example i want:

Top 10 submitters (filter for a parameter(external link, discussion, all)). The URL should be:

GET /users/top?type=ext
GET /users/top?type=disc
GET /users/top # for all

Or maybe it should be:

GET /users?top=ext
GET /users?top=disc
GET /users?top=all

The same but with posts:

Top 10 commented post (filter for a parameter(external link, discussion, all)). The URL should be:

GET /posts/comments?type=ext
GET /posts/comments?type=disc
GET /posts/comments # for all

Or maybe it should be:

GET /posts?top=ext
GET /posts?top=disc
GET /posts?top=all

Any of above options are good for you or it should be another way?

Regards

Upvotes: 0

Views: 106

Answers (2)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57194

As usual; REST doesn't care what spellings you use.

One place you might look for inspiration is... stack overflow itself. Do these URI look familiar?

/questions?sort=newest
/questions?sort=featured
/questions?sort=votes

The API has pretty decent documentation, which will also offer hints at decent spellings to deal with paging and search ranges.

That said, IMDB takes a different approach - The Shawshank Redemption uses a straight forward "I am an element of a collection" spelling

http://www.imdb.com/title/tt0111161/

But the top rated titles of all time? they appear as a chart

http://www.imdb.com/chart/top

But i want to know if there is a standard according to @Hawkes answer or there is no standard at all.

No standard at all; just local spelling conventions. Which is, to some degree, part of the point of REST: the server can use whatever spellings for URI make sense, and the client just "follows its nose" based on its understanding of the processing rules for the media type and the data provided by the server.

Upvotes: 1

Hawkes
Hawkes

Reputation: 467

I like to think of the REST URI as a model representation in itself.

So /users/top doesn't make a lot of sense but /posts/comments seems to be fine (as comments could also be a different model). But for your case, I recommend other set of query parameters as they're widely used for filtering & sorting requests. So in your case, I'd recommend something like:

GET /users?sort=ext&order=desc&limit=10

which would help me understand that I'm requesting 10 user resources which have been sorted for ext in the descending order. (you can even change it to type=ext if you want)

Upvotes: 1

Related Questions