An example of modeling REST web services

A Simple REST web-service model

UML Model of a RESTful service

What does this model represents?

Look at the above model for a minute (Click the model to enlarge). What can you say by looking at this picture?

There is  BookmarkService from which there is a path /users . The Users resource contains a method create which is also tagged as POST. Probably this means that I can do a post on http://<baseurl>/users to create a new user.

Further left is another path tagged {username} which suggest that something like …/users/{username} can be done. Consider anything in curly brackets as a variable, a placeholder, so actual url would be something like http://<baseurl>/users/john or http://<baseurl>/users/tom. Operations allowed on this are as you can see from the UserName resource class are GET, PUT and DELETE which have obvious effects. Similarly to get the list of all bookmarks for a user you would need to do something like http://<baseurl>/users/john/bookmarks. Armed with this knowledge you can read the entire diagram to see the entire set of web services that are being provided by this service

Now imagine if I had shown the code instead of the model above. It would have taken much more time and space to figure out what that code does and with much less certainty.

Does this model has any further use?

After all off what use is this model, if the code meant to implement these concepts have no link to this model and is hand written. In that scenario, code is the ultimate truth and you can ignore the pretty model picture.  Well not in this case. You can generate almost complete implementation from this model by running a transform from it. In Rational Software Architect ( ) the team that I work for, we have REST transforms which can take this model and generate most of the boiler plate code for you, such that you are left to fill only the business logic part of the code. What’s the boiler plate code that’s getting automatically generated.

  1. Classes with methods are automatically generated with JAX-RS annotations and comments.
  2. The params extraction is automated.
  3. A report from the above model is generated which can be published as a document and circulated to all external stake holders.
  4. With proper JAX-RS runtimes installed, the routing is taken take automatically by the runtimes and user doesn’t need to worry.
  5. The BookmarkService class can directly be used as a servlet for container that are JAX-RS aware.
  6. With little modification, the original model can be retargetted towards a different implementation also.

You can imagine your REST services as your public API and a good way to control your API would be to have all addition , deletion or modification to the API go through this model, so that all decision can be discussed and reviewed before being approved.

Next Steps

If this gets you excited and you can imagine the amount of effort you will save, besides being able to discuss your services with other using the model, take a look at the detailed article by my colleague  has written on RESTful web services modeling support   in the newly released version of RSA.

In case you are interested in a live talk and demo, my talk is scheduled during the Innovate 2011 conference in Bangalore. I will be talking about the RESTful web-services modeling capabilities in RSA (Rational Software Architect) in detail along with a demo. I will be available for discussions through out the conference.

4 responses to this post.

  1. [...] An example of modeling REST web services [...]


    • Posted by Ankur Deshwal on July 22, 2011 at 6:35 PM

      Looks great!!

      However the pretty picture looks interesting always for small models. While the real life codes(and design requirements) tends to blow up all the software engineering methods involving the graphical interface for design and modeling. I believe we still lack proper human-machine interaction interface to explore such nice graphical tools. :)

      But that does not in any sense should stop improvising with whatever possible.

      Thanks for the uncluttered and simple article for the introduction to REST.


      • In the model that I have shown in the diagram, the effort is to model the REST API that a BookmarkService will provide. From this model the code is generated automatically and there is support for reapplying you changes without losing your existing code ( as you will keep on enhancing your APIs ). The implementation of these API would require you to add only the business logic part of code ( for example if you want to store the url in a db or xml file , or if you want to keep track of number of free book marks allowed etc ), but other mundane concern like routing the http GET/POST/PUT/DELETE method to appropriate method/class, extracting parameters like {username}, adapting the return types etc will be automatically taken care of ( in partnership with the JAX-RS runtimes ). Generation of documentation is also automated. To this effect, I think its much more productive to create a model, than to jump directly into code. Ofcourse the main benefit is that it lets you also discuss your API with other stake holders and make changes, which you can’t do with just plain code being projected.

        Having said that, I do agree that not all situations are where the modeling returns justify the effort, but that’s the topic for another post (coming soon …) :-)

  2. Posted by SS on July 22, 2011 at 11:18 AM

    Looks interesting!


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


Get every new post delivered to your Inbox.

%d bloggers like this: