Posted on by & filed under Content - Highlights and Reviews, Programming & Development.

Writing user authorization systems RESTfully can be tricky for any newcomer to REST. This blog post is meant to provide some ideas on how you can do this in a RESTful manner.

When people first think of user authorization, they often think in terms of commands:

  • Sign in
  • Sign out
  • Forgotton password
  • Sign up verification

It’s common to see URI’s such as:

With a POST to that URI with parameters like:


Or a GET to a URI such as:

These are examples of how people think of a command that is done to a user.

And in the service handling those commands you’ll often see them lumped into a single service or controller:

One possible reason people think in terms of commands in terms of authorization systems is that it feels right. We as programmers have always done it like that. You have a user, and you want to sign them in. Or you have a user that has forgotten their password, and you want to reset it. These are things that are done to a single object – a user. And there’s nothing wrong with that per se. But its not very RESTful.

So if you think of user authorization in terms of resources, you might start to break down a User class into different classes:

So to handle sign in, you would POST to /sessions in order to create a new session.

So your Session service (or controller) may look like:

So here, we are tying together three resources: User, Password, and Session, in order to handle our sign in. Read Chapter 1.2. Thinking in Resources in Rest in Practice for a good discussion about REST services.

The user is located by looking up the email address against the available users. The user holds a reference to a password, so that it may authenticate the password against the found user. And finally, a new session is created for that user.

Bear in mind that you’d probably refactor down those methods in a single helper method on user for production code. In order to handle sign out, it’s a case of deleting the session, so you would DELETE /sessions/session_id:

In order to handle forgotten passwords, in terms of resources, there are a couple of options. You can drive the functionality directly using the passwords resource:

The benefit of this approach is that it’s simple to understand, and you are working directly with the resource you wish to manipulate.

So to perform the forgotten password functionality, you DELETE to /passwords/123. To change the password, you simply PUT to /passwords/123 with the new password and confirmation.

The downside of this approach is that you need to persist the password id on the client end somehow – usually in an encrypted cookie. The other downside is that you could argue that no operations on passwords should be done without involving the user – because password belongs to the user (think aggregate root in domain-driven design).

So another way is to drive the functionality through the user class, using the session key which was created when sign in occurred:

The upside of this approach is that you don’t need to persist a password id client side (instead using the session key as the ubiquitous user access), and you also drive the password functionality through the user. The downside is that it’s slightly breaking REST. By POSTing or DELETEing to /passwords/{session_key} the {id} should be the id of the resource you’re referencing. By sending the session key as the id, you’re being slightly naughty.

Now, in systems where you’re accessing movies or songs or some solid resource, you’d certainly expect the {id} to directly reference the id of the resource in the system. As noted before, however, the case of user authorization systems is traditionally tricky due to the command-based nature of user authorization functionality.

It’s all about style, and preference, and what makes sense to you, as the developer. It should be noted that in general, RESTful sub-systems don’t always have to religiously stick to the resource pattern. Sometimes, it just doesn’t fit, and it you shouldn’t struggle to make a sub-system RESTful if the command pattern makes more sense (and there’s nothing wrong with the command pattern!).

For more details about REST, see the ebooks referenced below.

Safari Books Online has the content you need

REST continues to gain momentum as the best method for building web services, leaving many web architects to consider whether and how to include this approach in their SOA and SOAP-dominated world. Rest in Practice offers a down-to-earth explanation of REST, with techniques and examples that show you how to design and implement integration solutions using the REST architectural style.
The basic rules of REST APIs – “many nouns, few verbs, stick with HTTP” – seem easy, but that simplicity and power require discipline to work smoothly. REST API Design Rulebook provides the next steps for implementing complex REST projects on simple and extensible foundations.
SOA with REST: Principles, Patterns & Constraints for Building Enterprise Solutions with REST is the first comprehensive tutorial and reference for designing and building RESTful services as part of service-oriented solutions and in conjunction with service-oriented architecture (SOA). This book demonstrates that REST is not only a suitable medium for building truly service-oriented solutions, but also that the service-oriented architectural model is a necessary foundation for REST technology architectures to realize their full business potential.

About the author

Ben Keeping is a freelance developer based in the UK. He currently specializes in applications written in .NET and Ruby, using lean and agile techniques. He can be contacted @benkeeping.

Tags: command pattern, GET, POST, REST, RESTfully, URI, User Authorization, User class,

Comments are closed.