CODEWITHSUNDEEP
apirest
keisar
keisar

Reputation: 5326

How should my URIs be structured to be considered RESTful?

I started working on a public API for my project, I thought of making it RESTful.
I keep seeing articles about how some APIs (like twitter's) are not really RESTful and I want to try and make my API as RESTful as possible (it seems that it is not that simple :) )

Currently there is one thing I am contemplating on, lets say there are two resources, users & movies, each user has a list of movies, I want to create a REST api for getting all the movies for the currently connected user, what is the correct way of designing this ?
(XXX is some kind of authentication token - I haven't decided what authentication to implement yet)

  1. GET /movies?token=XXX
  2. GET /users/XXX/movies

or maybe something else all together ?

Also if anyone can direct to me to a good reading on the subject, something that will help me create my public API as RESTful as possbile, it would be a great help!

Upvotes: 2

Views: 148

Answers (2)

ank
ank

Reputation: 116

Reading Roy Thomas Fielding's doctoral dissertation, entitled Architectural Styles and the Design of Network-based Software Architectures, proved to be a good way for me to understand the REST architectural style. Seems daunting at first, but it's full of insights that can help you design a better API.

Upvotes: 2

Michael Venable
Michael Venable

Reputation: 5051

I really liked Restful Web Services by Leonard Richardson. He explains REST, how some sites misuse it, how to use it correctly, when to use query strings versus putting the info in the URI path. He also covers authentication, but he's kind of brief on that topic. He spends a good bit of time explaining why REST is better than SOAP -- I enjoyed it, but other reviewers seem to feel it was excessive. He uses Ruby/Rails in most of his examples.

Out of your two examples, I prefer "GET /users/XXX/movies" over the first. Using the query string is good for searches or optional parameters. Something like google.com/?q=batman or /users/XXX/movies?page=2. Since you are looking at the movies of a particular user, it makes sense for the URI to match that structure, and option 2 does that.

Some sites aren't truly RESTful because they provide methods like 

GET /GetUser?token=XXX
GET /SaveUser?token=XXX&name=YYY

A truly RESTful service would obey the existing HTTP commands and operate on resources, not functions. According to the book, if you following the HTTP protocol, you usually don't need words like "get" or "save" in your service names -- they are provided by HTTP.

GET /user/XXX
PUT /user

Hope this helps. I don't have any good web resources, but I'd recommend giving that book a try.

Upvotes: 4

Related Questions