Resources

Resources are at the heart of REST.  You are already used to resources as a web browsing consumer.  A resource is not something specific to REST, instead it is the first thing you probably want to consider when architecting a RESTful application.  A resource is simply the entity, item, or thing you want to expose.

Perhaps you have approached application architecture using one or many of several modeling and design techniques.  Data First practitioners typically begin with databases and data models.  DDD proponents like to begin by modeling around business entities and interactions, while their cousins in the BDD camp model around business activities.

When you decide to apply REST you will need to think a lot more about data entities and domain objects as resources.  Your existing models may or may not closely map to resources.  The shift in thinking may appear slight, but is very important.  It centers around making things  addressable.  Each resources must by uniquely identifiable as we will see in the next section.  We are used to identity with most data entities, but our domain objects may not always be as easily identifiable.  Likewise, our data entites may have identity, but not map to a resource. 

Consider the classic customer and order scenario for example.  If each customer and each order can be identified then it will be easy to design RESTful systems around them.  However, if the model requires a lot of context then our challenge is a little bit larger.  Perhaps we must first identify a partner, then a year, then a customer, and finally the order.  Yes, that is a design smell in general.  It makes fetching an order very difficult.  Developing RESTfuly would only further expose that difficulty.  Identifying your resources up front will help you reduce the possible impedance mismatches you might end up with between what you want to expose and your data or domain models.

REST is about interacting with Resources!

URI’s

REST defines the identity of a resource via URI.  Each resources has a unique address in URL form (ie. using the http protocol).  Interaction with a resource will take place at its URI.  As an example, my twitter status feed resource URI is http://twitter.com/optionstrict.  That URI is unique to my feed and that is what you expect to find at that URI.  In the Twitter databases or domain models my account may be referred to by the string optionstrict, or perhaps as some random number or guid.

To consume my status history via a service interface twitter provides another URI at http://api.twitter.com/1/statuses/user_timeline.json?screen_name=optionstrict.  I would actually prefer to have access at the same URI for html, json, and xml formats.  Twitter probably has its reasons for distinguishing API access from HTML rendering, but they have actually complicated their architecture by doing so.  When designing the URI’s for your resources, make them easy for your users to work with. 

Representation

Lets continue with the twitter example to describe what is meant by Representation.  Given a URI and a Resource, what will your consumers receive when they issue a GET request to the URI?  Twitter chose a representation of my account and included status history and profile for the response at http://twitter.com/optionstrict.  They decided to put a representation of my profile photo at http://twitter.com/account/profile_image/optionstrict.  In your REST solutions you will need to consider how you want to represent a resource at its URI.  Each representation will have a unique URI. 

Representations are also important for manipulating resources.  You must define the representation required to create and update resources.  Twitter status updates require a text representation with a maximum of 140 characters.  They allow additional values in the status representation, such as latitude and longitude.  Your REST solutions similarly must define representations for Requests and Responses.

I hope that this short introduction has helped you to see that the core essence of REST is simple and fairly obvious.  As you look at your current solutions what are the resources you are exposing?  Could you make those resources identifiable by URI?  What representation would you place at each URI?  What representation would you require for manipulating a given resource?

Also, notice I did not mention much about data formats, Content Type, Mime, etc.  Those details can cloud your design if you try to start with them. If you can’t wait for my post about how REST handles html, json, xml from the same URI, then start googling Content Negotiation, Accept header, and Content-Type header.

oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.

Providers must specify one or more URL scheme and API endpoint pairs. The URL scheme describes which URLs provided by the service may have an embedded representation.

Requests sent to the API endpoint must be HTTP GET requests, with all arguments sent as query parameters. All arguments must be urlencoded (as per RFC 1738).

{
"provider_url": "http://www.youtube.com/",
"title": "Insert a YouTube Video With oEmbed Wordpress 2.9",
"html": "<object width=\"480\" height=\"295\">
    <param name=\"movie\" value=\"http://www.youtube.com/v/6lbDyXu7gUQ&fs=1\"></param>
    <param name=\"allowFullScreen\" value=\"true\"></param>
    <param name=\"allowscriptaccess\" value=\"always\"></param>
    <embed src=\"http://www.youtube.com/v/6lbDyXu7gUQ&fs=1\" type=\"application/x-shockwave-flash\"
        width=\"480\" height=\"295\" allowscriptaccess=\"always\" allowfullscreen=\"true\"></embed></object>",
"author_name": "adriarichards", "height": 295, "width": 480, "version": "1.0",
"author_url": "http://www.youtube.com/user/adriarichards",
"provider_name": "YouTube",
"type": "video"
}

Consumers may wish to load the HTML in an off-domain iframe to avoid XSS vulnerabilities.

Resources

Resources are at the heart of REST.  You are already used to resources as a web browsing consumer.  A resource is not something specific to REST, instead it is the first thing you probably want to consider when architecting a RESTful application.  A resource is simply the entity, item, or thing you want to expose.

Perhaps you have approached application architecture using one or many of several modeling and design techniques.  Data First practitioners typically begin with databases and data models.  DDD proponents like to begin by modeling around business entities and interactions, while their cousins in the BDD camp model around business activities.

When you decide to apply REST you will need to think a lot more about data entities and domain objects as resources.  Your existing models may or may not closely map to resources.  The shift in thinking may appear slight, but is very important.  It centers around making things  addressable.  Each resources must by uniquely identifiable as we will see in the next section.  We are used to identity with most data entities, but our domain objects may not always be as easily identifiable.  Likewise, our data entites may have identity, but not map to a resource. 

Consider the classic customer and order scenario for example.  If each customer and each order can be identified then it will be easy to design RESTful systems around them.  However, if the model requires a lot of context then our challenge is a little bit larger.  Perhaps we must first identify a partner, then a year, then a customer, and finally the order.  Yes, that is a design smell in general.  It makes fetching an order very difficult.  Developing RESTfuly would only further expose that difficulty.  Identifying your resources up front will help you reduce the possible impedance mismatches you might end up with between what you want to expose and your data or domain models.

REST is about interacting with Resources!

URI’s

REST defines the identity of a resource via URI.  Each resources has a unique address in URL form (ie. using the http protocol).  Interaction with a resource will take place at its URI.  As an example, my twitter status feed resource URI is http://twitter.com/optionstrict.  That URI is unique to my feed and that is what you expect to find at that URI.  In the Twitter databases or domain models my account may be referred to by the string optionstrict, or perhaps as some random number or guid.

To consume my status history via a service interface twitter provides another URI at http://api.twitter.com/1/statuses/user_timeline.json?screen_name=optionstrict.  I would actually prefer to have access at the same URI for html, json, and xml formats.  Twitter probably has its reasons for distinguishing API access from HTML rendering, but they have actually complicated their architecture by doing so.  When designing the URI’s for your resources, make them easy for your users to work with. 

Representation

Lets continue with the twitter example to describe what is meant by Representation.  Given a URI and a Resource, what will your consumers receive when they issue a GET request to the URI?  Twitter chose a representation of my account and included status history and profile for the response at http://twitter.com/optionstrict.  They decided to put a representation of my profile photo at http://twitter.com/account/profile_image/optionstrict.  In your REST solutions you will need to consider how you want to represent a resource at its URI.  Each representation will have a unique URI. 

Representations are also important for manipulating resources.  You must define the representation required to create and update resources.  Twitter status updates require a text representation with a maximum of 140 characters.  They allow additional values in the status representation, such as latitude and longitude.  Your REST solutions similarly must define representations for Requests and Responses.

I hope that this short introduction has helped you to see that the core essence of REST is simple and fairly obvious.  As you look at your current solutions what are the resources you are exposing?  Could you make those resources identifiable by URI?  What representation would you place at each URI?  What representation would you require for manipulating a given resource?

Also, notice I did not mention much about data formats, Content Type, Mime, etc.  Those details can cloud your design if you try to start with them. If you can’t wait for my post about how REST handles html, json, xml from the same URI, then start googling Content Negotiation, Accept header, and Content-Type header.