2

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!

Paul Turner
  • 38,949
  • 15
  • 102
  • 166
keisar
  • 5,266
  • 5
  • 28
  • 28
  • Asking "what is the right way to do X" is asking for a subjective answer and is likely to result in this question being closed. Could you re-word your question to be something which has a definite factual answer? – Paul Turner Nov 30 '12 at 15:30
  • hi Tragedian, I thought since REST has specific structure and rules there would be only one (correct) answer, am I mistaken ? Should I rephrase the title or the whole question is written badly ? could you give me an example as I don't really see to what I can change this :/ – keisar Nov 30 '12 at 16:02
  • 1
    yes, rest is not a One True Path, it's a set of constraints, and what your URL looks like is not one of them (as long as it represents a noun and not some kind of action/verb) – Nicholas Shanks Nov 30 '12 at 16:08
  • @Nicholas your comment was what I was looking for :) it seems my approach was wrong. Thanks! – keisar Nov 30 '12 at 16:15
  • @Tragedian I edited the title, hopefully this is better... – keisar Nov 30 '12 at 16:19
  • @keisar I should add, although URIs are not constrained by REST, a good REST API should have a well-designed URI space! – Nicholas Shanks Nov 30 '12 at 16:53
  • @Nicholas back to being confused... what is the definition for a "well-defined URI space" ? – keisar Nov 30 '12 at 16:57
  • One that is not illogical? It's subjective, ask an artist :) – Nicholas Shanks Nov 30 '12 at 22:23

2 Answers2

4

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.

Michael Venable
  • 5,011
  • 3
  • 23
  • 20
  • I totally concur with this answer. especially the line **I prefer "GET /users/XXX/movies" over the first. Using the query string is good for searches or optional parameters** – Nicholas Shanks Nov 30 '12 at 16:09
  • Thanks Michael, I'll give the book a try. Also, is it OK to pass the auth token as a header or should it be passed in the URI ? – keisar Nov 30 '12 at 16:12
  • 1
    try to use one of HTTP's existing authentication schemes if you can: an Authorization header with either Basic or (better) Digest token, but if you can't and you CAN pass it as a header from the client (some kind of scripting reqd.) then by all means do so. keeps the URI clean. just be sure you return a 401 when people are not auth'd so that caches don't save a failure response – Nicholas Shanks Nov 30 '12 at 16:19
  • But if I would to use a header or built-in authentication then the URI would look like this: GET /users/movies, and the current user will be taken from the auth header, I saw complaints about this type of URI, that it's not RESTful because the same URI returns different results for different people (see here http://stackoverflow.com/questions/3408191/is-the-twitter-api-really-restful) - I misunderstood ? – keisar Nov 30 '12 at 17:42
  • 2
    You can handle this by keeping the URI as /users/keisar/movies. If only keisar is allowed to view his movies, then the URI stays the same but you add authentication -- so /user/keisar/movies will work but /users/michael/movies will be denied. If a user can view any other user's movies, then the URI is still the same but no authentication is needed. You're not using authentication to determine what data to return; you're using it to determine if the user can view the requested resource. – Michael Venable Nov 30 '12 at 18:39
  • Thank you Michael & Nicholas for your help & patience :) everything is much clearer now! – keisar Dec 01 '12 at 09:41
2

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.

ank
  • 106
  • 5