Hi Suma,
I agree that you can find some other links that will build up your knowledge of REST 1st, because there are a lot of links that assume the basics are known or at such a high level that certain assumptions cannot be made from them...
A useful article from Zapthink gives a good explanation of how state works in a RESTful application. The last 2 letter of the acronym for REST is State Transfer, so this gives you an idea of how state is managed, but this article talks about application state vs. resource state. Ignore the fact it talks about Cloud computing as the explanation stands on its own:
http://www.zapthink.com/2011/11/22/the-secret-to-a-restful-cloud/
As far as the WSDL comment, if you return hypermedia links in your representations to drive your app, you do not need a service specification (and very little documentation beyond the home URL or docRoot entrypoint to your app. If you are using XML as the format for your REST representations, then something like
WADL can be used. If you are using JSON, then there is no current formal specification for JSON although there are groups working on that. A large part of the JSON community fears that using a specification in JSON will render it inflexible during design as WSDL has done with SOAP. I don't necessarily agree with that notion. Here's a few links to people looking at JSON specifications:
http://json-schema.org/http://www.wrml.org/
Also I'm copying a private blog post I've made at work on REST to help guide you to some good starters for REST design as I was researching REST. Can't attach the powerpoint here, so you will have to ignore that comment in the blog post. Hope this helps your journey
__________________________________________________________________________________________________________________
Moving from CRUDyRest to HyperRest
So I started to do some more research via books like
Rest in Practice, Internet blogs and such. I came across quite a debate of what was considered a RESTful architecture. I lot of it stems from the work of Leonard Richardson dubbed the
Richardson Maturity Model. The blog by Martin Fowler linked in the previous sentence discusses the model as steps toward the glory or REST. But Roy T. Fielding who created the
REST dissertation made it pretty clear in his
blog that hypermedia was a prerequisiteto a RESTful architecture.
As I found more information and started exploring this concept, I realized that the 4 levels (level 0 to 3) of the RMM are not steps to build a RESTful architecure. These are learning steps, or evolutionary steps for an existing HTTP service implementation. It doesn't make sense to start at one step and build to the others unless your architecture is already at a step.
My first inclination in designing a RESTful system was to start at defining the resources and their relationships as most people do. This technique naturally steers you toward building an RMM level 2 CRUDy REST API. Sure, you can enhance your system into a level 3 from there, but for all those client apps that relied on the resource structures and relationships to build their client code - they are now coupled to that model and probably will need to change to take advantage of the hypermedia aspect coming down the road. Also any changes to the resource and resource relationships (which can inevitably happen when trying to get to level 3) will break the application code for those early-adopting clients.
The author of the Richardson Maturity Model, Leonard Richardson wrote an
abstract on how he built a client (in Python) to take advantage of the Hypermedia As The Engine Of Application State (
HATEOAS) concept over RESTful services. This was to show results on the advantages of this approach as it seems to be hard to grasp for many developers.
So I'm now attempting to identify a checklist (in no particular order) of analysis/design techniques for building RESTful architectures.
Although I have not prescribed a particular order to promote an iterative approach, all good designs and architectures start with enough requirements and analysis to design and build something useful.
I'm not going to go into a soapbox on Agile vs. Waterfall and Incremental vs Iterative here as it's not the point of this post. I will probably be expanding on this in the future. Just resign yourself to the fact that you are not going to know 100% of all the requirements to design your entire system before providing workable code.
Here's those initial analysis techniques to start off with:
Come up with a good (or cool) REST API name and concept that preferably aligns with the domain area you are tackling (for the REST in Practice book this is the "Restbucks" system)Identify Actors/Personas/Roles for those that will be using the REST API. What are their needs and motivations?Identify the Business Process / Sagas that will be going on in your system. This may be very basic and simple at first, but will evolve more.Identify Use Cases / User Stories that will involve your systemIdentify the common base media types that clients will want to use to communicate with the REST API (i.e. JSON, ATOM, XML, etc)
These analysis techniques can be used in any order to drive out refinement for each other. For example I can start with an initial user story and use that to identify some personas (or actors). This user story may lead identifying another user story that can then be filled out in the saga / business process.
After getting a good set of analysis data to where you have a good direction you can then start designing the API.
Here' the design techniques you can use on the analysis to build a good API.
From the use cases / user stories identify your entry points into the REST API. Then build a home resource (or URI) that returns a representation with transition links to these entry points. This is similar in concept to the home page of a website providing the links needed to get started based on a user's need.For the entry points, design the representation that will bring back the appropriate transition links for the next possible steps in the use case / user story. The allowable transitions states will depend on where in the business process / saga the client app is (think of this as business process state). These transitions can also be constrained by the internal state of the resources.Start building your resources and resource relationships. This is essentially designing the URI structures returned by the transition links. Remember that the structure of your resources and their relationships to other resources should be abstracted from the client via the hyperlinks returned in the representations as much as possible.
Ideally a client using a well designed REST API that follows these techniques should be able to to the following...
1. Perform a GET on the home URI
2. Extract the entry point links from the representation
3. Use one of the transition links to perform another REST call based on client decision logic
4. Extract the transition links from the next representation
5. Repeat steps 3 and 4 until business process is done
This flow is very similar to the one described in Leonard Richardson's
abstract above for how someone browses the WEB...
1. Retrieve a hypermedia representation of the home page.
2. Decode the representation to determine the current resource state.
3. Based on the representation's semantic cues, decide which hypermedia link or form is likely to bring you closer to your goal.
4. Click the link or fill out the form. Your browser will make another HTTP request and the result will be another hypermedia representation.
5. Go back to step 2 and repeat until the resource state is to your liking.
Through this process the client should never have to generate or append to a URI in order to make the RESTful call. It only relies on the link name for out-of-band information.
For an animated presentation of this process, you can download and view the power point deck attached.
In a follow-up blog, I will discuss the challenges of reducing out-of-band information for the client app. For calls with no parameters or input representations this is pretty easy, but can be more involved when using query parameters, path parameters, and input representations.
