REST services and URL’s

When designing and building REST services the URL’s used take on a rather important part. So it pays to think a lot about the URL structure up front.

Basically a URL is used to identity a recourse. So it kind of behaved like a primary key in a database. There are a few big differences to keep in mind. Unlike a primary key a resource can have multiple URL’s pointing to the same resource. Another difference is that we often have a URL for a collection of the same items. So for example:

• http://localhost/books/123
  Points to a specific book identified by 123 (whatever that might mean).
• http://localhost/books
  Points to the collection of books.
• http://localhost/books/author/douglas+adams
  Points to a collection of books authored by Douglas Adams.

Some things are not resources. An often made mistake is to model operations using the same URL scheme. For example:

• http://localhost/books/search/robot
  This would search the book collection for books about robots. But searching is an operation so I believe that this should be modeled using the http://localhost/books URL and either add a filter using either query parameter or an HTTP header.
• http://localhost/login
  Login in is definitely an action and not a resource we can retrieve. And secondly it suggest some shared state between the client and the service, another thing that is better to avoid.

This might seem simple enough, and it really isn’t rocket science, but it can still be harder that it seems. And remember that the URL is just there to identity a resource, it doesn’t really tell us what we can do with it yet. In some cases all we can do is GET the resource but in other cases we can add new ones using the URL or we can update or delete existing resources.

Enjoy!

www.TheProblemSolver.nl
www.dotnetevents.nl