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:

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.





2 thoughts on “REST services and URL’s

  1. Why would search/something not be a resource?
    Because it’s denormalized? I think is a resource (might not allow PUT or DELETE)

    For login, have you considered hypermedia?
    – create a login resource that describes what data needs to be posted + endpoint.
    – then upon posting it, redirect to account/username or similar, which is a resource

Leave a Reply

Your email address will not be published. Required fields are marked *