REST-Based service design

February 12, 2008. Series [ REST-based Service Design ] Tags [ REST API ]

Just wanted to walk through a quick REST-style API design exercise. Let’s suppose I want a service that lets folks maintain a list of favorite foods. Just as a quick strawman design, let’s walk through some URIs and supported operations:

• http://host:port/path/{userid}/favorites

  • GET on this URI returns a list of the current user’s favorites. List might be empty. PUT on this URI overwrites an existing list of favorites. DELETE on this URI sets the list of favorites to the empty list.
    

• http://host:port/path/{userid}/favorites/{food}

  • GET on this URI returns something (really, we just want a 200 status code) if the food is a favorite, or returns 404 if it is not. DELETE on this URI un-favorites the food for the user. PUT on this URI makes the food a favorite.
    

So, questions for the audience:

1. Does this look reasonable?
2. Does the use of PUT look right, or would you use POST here?
3. How about the use of DELETE to set the full list to the empty list? Does it make sense to DELETE a URI and then be able to GET it and have something be there?