In this post we will talk about building RESTful services. However before we do that I would recommend reading the previous part of the series



One of the biggest roadblock in developing REST base systems are influencing technical factors like Object Oriented design, abstractions or the technologies that the architects are familiar with. This situation could even become worse if the architect has good technical background in web technologies like MVC and thinks about implementation in these technologies while designing REST services.


Design Workflow for Agile Board

We need to think independently of any technology or other influential factors that might corrupt our design. We should not think about classes or methods while designing a RESTful system and I think the best way to do that is stay away from the computer and use pen and paper for the design purpose. To practice that let’s think of the process of managing the task tracking workflow with the example of an agile board.

Agile Board

Agile Board


Let’s think about the process of managing an agile task board. When we want to design the workflow, the first thing that we look at are the elements that enable the workflow. The elements that enable the workflow are:

  • Agile board – The agile board is divided into 5 sections to do, design, code, test, done. When a new task is created it would go in the “to do” list. When a team member will start of work on a task then it would be moved to the “design” list and so on to the different lists.


  • Sticky notes – These are the communication interface for communicating among the team members as well outside the team as well. The sticky note will have the story number, description, estimate and Assignee.
Sticky Note

Sticky Note

This would seem like a very simple workflow but we are making an assumption here that all the team members know how to move tasks across the agile board. We are also expecting the team to know that new tasks will be going in the “to do” as well. What if we change the process then we would have to share the same knowledge with complete team. We could eliminate all of this by a simple solution. We could define icon for each of the lists on the agile board.

Agile Board With Icons

Agile Board With Icons

We also add the corresponding items to the sticky node as well then we could easily track the current stage of the task. Now in the sticky we could see the icons of the various stages of the task starting from “to do” till “done”.

Sticky Note Icons

Sticky Note Icons

We can track it by simply crossing out the stage which the task has already passed through. In the image below it clearly shows that the task has passed though the “to do” and “design” list and currently in the code phase.

Sticky Note Stage 3

Sticky Note Stage 3

Whenever any changes happen in the sequence or number of stages we just need to update the board and the sticky and no other communication is needed to anyone. Suppose we remove the design phase from our systems. Now we could simply update the board and the sticky and everyone using it would be able to understand as what needs to be done. Whenever a task is being moved then the team member crosses off the icon of the current state and look at the next icon and move the task to that list.

Agile Board Without Design

Agile Board Without Design

Sticky Note Without Design

Sticky Note Without Design

Now if you image this kind of change to be done in an RPC system then it would require versioning and redeployment of the clients so that they are aware that they have to call a different method.  And this might be a reason for the failure of the RPC system. However in this model our client workflow hasn’t changed at all whereas the system workflow has changed. And hence it adheres to the RESTful principle where I could change the system workflow without changing the client workflow. The client workflow is still the same where the team member has to cross off the current matching icon and look for the next matching column on the board and place the sticky note in that column.


Software design for Agile Board

Now when we are comfortable with the idea and workflow of a physical agile board, we can go ahead and design for a software based agile board. Like any software system before we start working on the software we will list down a few high level requirements. Since this is an example we will keep the requirements pretty simple:

  • Add new tasks to the backlog
  • Move task to design
  • Move task to code
  • Move task to test
  • Move task to done

State Transitions

We have a simple domain hence we have a simple state transition model. From the starting state we could reach to different states each of which is a collection tasks. You could see in the diagram below that we have captured two types of information:

  • Application states such as entry and task collection. This will be useful when we will design the media type later in the module.
  • States that a task can go through like to do, design, etc. This information will be used in the next section of the module to identify resources.
State Transitions

State Transitions

Using this state transition our client would have to know about only one url that is the entry url and then the client should be able to discover all the other services from there.


Identifying the Resources

Now let us create the resources corresponding to the states for the application. The resources with their urls are shown below in the image.



  • /tasks – The entry point of the application. It supports the following operation

o   GET – fetches the hypermedia elements for navigation and addition of a new bug to backlog.

  • /tasks/todo – The list of the tasks that have not been started yet.

o   GET – fetches the list of tasks in the todo list

o   POST – adds a new task to the todo list

  • /tasks/design – The tasks that are currently in the design phase

o   GET – fetches the list of tasks in the design list

o   POST – adds a new task to the design list

  • /tasks/code – The tasks that are currently in code phase

o   GET – fetches the list of tasks in the code list

o   POST – adds a new task to the code list

  • /tasks/test – The tasks that are currently in test phase

o   GET – fetches the list of tasks in the test list

o   POST – adds a new task to the test list

  • /tasks/done – The tasks that are done.

o   GET – fetches the list of tasks in the done list

o   POST – adds a new task to the done list


Designing the representation of Resources

Once we have identified the application states, the transitions between them and mapped them onto the Uniform Interface element of resources and self-describing messages then we need to figure out how we want to represent our resources.

We have multiple options to decide from and Mike Amundsen in his book on Hypermedia API design, has broken these options into 4 questions.


  1. What format do we want to base our representation on?

This can be anything however the most common formats being used by the API today are JSON, XML, etc. We could choose to support multiple base formats as well.

  1. What type of state transfer will the API support?

The various types of state transfers could be

  • Read Only – In this type of state transfer, the client does not transfer any data to the servers.
  • Predefined – In this type of state transfer, the client is aware of the valid transfer elements beforehand via the media types shared by the server.
  • Ad-hoc – In this type of state transfer, the details of the valid transfer elements id shared with the clients in a representation.


  1. How will the domain elements map onto the base format?

There are 3 ways in which we could map the domain elements onto the base format.

  • Specific – In this style we create domain specific elements and attributes. For example in case of an XML based format we could create a task element having a title attribute.
  • General – This style as you might have guessed will be bound to a generic domain. It will not be specific to our business domain. One of the majorly used domain media type is Atom.
  • Agnostic – This style we would have a media type is completely unrelated to any specific business domain like HTML.
  1. What will be the application flow?

Application flow are the elements that allows a client to recognize and respond to possible state transitions. It could also be thought of as how the representation format will tell a client that a links exists and what the client can do with it. The application flow identifiers could be:

  • None – The client does not have any flow identifiers.
  • Intrinsic – The media type have built in elements for representing links and expressing the semantics.
  • Applied – The media type does not have the full capabilities to express the media type identifiers. This opens up the opportunity for the designer to apply attributes to the elements to express the identifiers. The example for this application flow could be seen in rel and class attributes of HTML.


Task Tracking Service Representation

Let’s make the choices for designing the task tracking service:

Base Format = HTML (since it’s easier to test)

State Transfer = Ad-hoc (since we will be using HTML forms to provide state transfer information to the clients. This way the client will just have to fill in the values and submit the form.)

Domain Style = Agnostic (Since HTML is domain agnostic)

Application Flow = Applied (Since HTML is a domain agnostic language so we will have to apply the custom application flow identifiers using an element of HTML)


Based on the above information and decisions we would need the elements for:

  • List of tasks
  • Link template to add a task
  • Link template to move task to to do
  • Link template to move task to design
  • Link template to move task to code
  • Link template to move task to test
  • Link template to move task to done
  • Navigation links

The advantage of using the Hypermedia design is that not all these elements will exits for each of the states. When a task is in to do state then only the design link will be visible and so on. This is how a hypermedia enabled design will help the client in deciding the right thing to do without any prior knowledge.


Mapping domain style to base format

Below is a table showing the mapping of domain style onto the base format which is HTML here. This is really useful way to document the representation. Here we are capturing all the details that client will need to recognize. Since in rest we do not have service description hence the client will look for a documentation top understand the representation.


Attribute Value AppliedTo Description
id task DIV Container for task state elements
name id INPUT[hidden] The task identity. Found as a child of FORM.move
  title Input[text] The task title state transfer element. Found as a child of
class all UL List of tasks
  title SPAN Task title. Found as child of LI
  description SPAN Task description. Found as child of LI
  new to do FORM Application flow identifier for adding a new task to to do
  next FORM Hints to the client for ideal next state transition. Should be used with FORM.move class
rel index A Navigate to index resource; should not be more than 1
  to do A Navigate to to do resource; should not be more than 1


Id – is used to represent a unique data element or block in a representation. We are using it here to identify the various state formats in the task tracking representation.

Name – is used to identify a state transition element within a representation. For example input elements.

Class – is used to identify any non-unique data element or block in a representation. Here we have used title to identify a task in the task list. It can have multiple value separated by space. This is used by the client to show available transitions instead of showing the same one dimensional list.

Rel – is used to identify a non-unique process flow element within the representation. Here we have used rel to identify the purpose for the link. It can have multiple value separated by space. This is used by the client to show available transitions instead of showing the same one dimensional list.


Sample Markup

The table provides a good visualization on how the representation looks like however nothing beats a dummy markup as shown below.

Sample Markup

Sample Markup

I have not provided any href and action attributes since the actual link value do not matter to the client. In REST url is not the most important part.

Also you would notice that I have specified move active next in the class value for the form. This would tell the client that it could show the optimal path as per the workflow.


Modifying the workflow dynamically

We will now go ahead and modify the workflow and remove the design phase. This will eliminate the transitions from todo to design, design to todo, design to code and code to design. It will add new transitions which are from todo to code and code to todo.

Modified Workflow

Modified Workflow

This will not have any impact on the clients since the clients do not need to know about the urls. The only thing that a client would have to know is about the new relationship values of both forms class and the rel attribute anchors since we removed a relationship value called design. Even if the client do not understand these, still the client doesn’t necessarily need to crash.


As per the new design a task in the todo list will never see a link to move it to design anymore. This design lets the client see only the valid operations that could be performed.



Generally rolling out the version 1 of a service is easy and difficulties come in rolling out new versions and fixing the bugs in the previous versions as there may be many clients using it. In REST the contract is the uniform interface.

Versioning within representation

In this form of versioning we do not need to do anything in form of formal versioning as we would be doing the versioning inside the representation. The core concept lies in the fact that the service could add whatever they want and clients would ignore whatever they do not understand.

Versioning the representation

When the semantics of a representation change as a result of the rename or deletion of an element then we might need to version the representation. Here we could make use of content negotiations to make sure the clients are able to get the representations they need in order function properly. We could transfer this representation metadata from the client to server by:

  • Embedding this information as part of custom media type name.
  • Using a parameter on http accept header like version or profile
  • Using custom http header

Versioning the resource

When the service is no longer able to keep the mapping between the resource and its associated profile then we would have version the resource itself. This would more creating a new resource rather than versioning the old one. But it will manifest in the resource identifier which is url in http terms.


Resources in Expression Blend

We will be using Microsoft Expression Blend 4 for this tutorial.

Resources are integral part of WPF and Silverlight. A resource in nothing but a name and value pair. Say for ex  – If I talk to a 2nd grade student and say my phone’s color is #FF000000, he would not understand what’s that that but when I say my phone’s color is black, he might or might not know what I am talking about.

This is the concept used by Microsoft behind using resources. This enables us to think in terms of names and labels as opposed to talking about the values. Let see this working in Expression Blend.

  • Create a new project in Expression Blend and name in Resources.

  • Create a rectangle on to the design surface.


  • Go to the properties tab and select the color green. Now when you work for any clients or customer designing applications for them they would have specification of color coding standards they want you to follow. Resources follow the same trend so that you can name your resource and use it at multiple places by just referring its name. We will see how that happens a little later.

 Click on the PropertyMarker as shown in the Image and select ConvertToNewResource. Every property in Blend has a property marker that means we can convert all the property in blend into a resource.   

  • Just name the property as MyGreen and click ok.

  • Now as would notice a couple of things have changed. Instead of the ColorPicker now we see Color resources and the also the list of resources available. Also as you can see the MyGreen is highlighted It is the Color that I am using currently.


  • Now just create a Ellipse and by default you would see that the color selected is the MyGreen color as Blend figures out that MyGreen is the color I am working and probably that’s the color I need.


  • Now Select the Fill as Gradient Brush


  • Now go to the Property Marker for the Gradient Brush and Go To local resource and select MyGreen. As you see are using MyGreen as both a SolidColor and a Gradient Color. The Color is the same but we are using it at different places.


  • Now go to the resources tab at the top and expand that user control and you would see that the MyGreen resource is available in the UserControl Scope.


  • Now if we change the color here we are able to change the color at all the controls using this resource. So using resource you don’t have to go to each and every control and change the color.

  • Now go back to selection tool and select the Ellipse. Now go to the Fill property marker of the Ellipse and select ConvertToNewResource.

  • Name it as BlackToMyGreen.

  • Now we see a Local Brush resource is available. You should know that a color is just is a 24bit value that probably represents some transparent color in the spectrum but a brush can be a single color or a set color or something else.


  • Now let’s go back to the Resources tab and expand the UserControl again and change the MyGreen to some other value. Now you would see that not only MyGreen has changed but also the BlackToMyGreen has also changed, so this implies that resources can use other resources as well.



Scope of Resources in Expression Blend

Now let’s talk about Scope of resources. Scope of a resource simply means where are we going to look when we are getting a concept. Let’s talk about a 2nd grader to whom we say my phone is black. Now he might know what is black, if that’s the case he is going immediately know what color you are talking about. Let’s say he doesn’t know what is black so he’s going ask his parents. Maybe his parents are able to answer it or they then go to their parents and ask what does black mean? This is exactly what scope means. You can define a concept at any level – object level, on a parent, on a document, in an application or a resource dictionary. Now when we say MyGreen then Silverlight or WPF will be able to figure out what is MyGreen. 

Let’s see this with the help of an example: 

  • Delete the rectangle and grid in the application we are working on and draw 2 identical Grids as shown below:


  • Now select the left grid and go to its properties. And select the background as Green.


  • You can click on the shortcut key and convert a color to resource.


  • And we will name it Grass and we will define it in the grid instead of the usercontrol. 


  • Now give a background to the other grid and create a new color resource in that grid named as Grass.


  • Clear the brush on both the grids using the shortcut below: 


  • Create a rectangle in one of the two grids. And using the color resources make the Fill of the rectangle as Grass. 


  • Now using the selection tool drop the rectangle from one grid to another by keeping the alt key pressed. 



  • What you see now is that the rectangle is using the local Resource Grass. Whenever an element is trying to figure out the meaning of the defined resources, it first looks into its own defined resources, then its parent resources and if it still is not able to find it will look further up till the root of the UserControl. And if still it is not able to find it there it will look for it in the application resources. But if a resource is defined at multiple levels then the closest one is adopted by the element. i.e. the resource is defined at a parent level as well as the application level then one the parent returns the meaning of the resource then the element stops looking and uses the same.


  • Let’s take another rectangle and drop it on the panel and this rectangle also uses the Fill as Grass but is not able to find it. That’s because the Rectangle does not know what Grass is, it asks LayoutRoot but LayoutRoot also does not know what Grass is, then it asks the UserControl which still does not know what grass is. So the unresolved resource gives us a blank fill.


  • Let’s go ahead and give it a SolidColorBrush and set the alpha value of it to 100 as whenever we get an unresolved resource blend gives it a transparent white brush. 


  • Now convert this to resource and select it to save at the application level.


  • Let’s go the resources tab and we see that Grass is defined as different color for different levels.



Resource Dictionary in Expression Blend


Let’s again talk about our 2nd grader who went to his parents to ask what is black, who in turn ask their parent as to what is black. Say their parent also does not know what is black so what they would do is grab one of the reference guides or resource dictionary and look for black color, if that resource dictionary does not have an answer for blue then they will check in other available resource dictionaries. In this case a Resource Dictionary is a single xaml file that contains key value pairs in it.

Let’s have a look at this with the help of an example:

  • Create a new solution in Blend named ResourceDictionaries and create a rectangle in it.

  • Convert that into a resource. But we will define it in a new ResourceDictionary.


  • As Soon as we do that a new xaml is added to the project. The reason for giving description of MyGreen here instead of the application level is the same as printing all the information in the book in the 2nd grader example. We can very easily transfer this dictionary to a different application.


  • Let’s just create a couple of more dictionaries. Right click the project and select Add new item and select Resource Dictionary and click ok.


  • Now we go the rectangle and change the fill color and save it into the resource dictionary 2. Change the color again and save it to the resource dictionary 3.


  • Now Delete the rectangle and just drag and drop a new one. What you will see is that this rectangle’s fill is yellow i.e. the color from the last resource dictionary. This happens because Blend creates a merged dictionary. So when a resource is found in a resource dictionary the element will look for any other occurrences of the same resource in all the resource dictionaries and will override the previous values with the new one. Below is how the resource dictionaries look like.


  • We can add or remove reference to a resource dictionary using the interface below.


  • And when we do the colors will follow a fallback mechanism.


I would like to state here that as of now i.e. Silverlight 4 all the resources are static resource and will take the value at the time instantiation. Where as in WPF we do have Dynamic Resources and at runtime everything will update.

Please find the source sode for the soultions at location below: 

Any comments, feedbacks or question are most welcome.