Table of Contents

  1. Overview
  2. Resources
  3. Representations
  4. Response Codes

Overview

The main concepts that you'll deal with when using the RestUpMVC framework are resources and representations. A resource is anything you want expose via your service. A resource could be a row in a database or it may represent a physical object like a webcam. If you were writing a project management service you may have a Project resource. Each project may have associated Tasks which would also be resources. A resource is never sent to or received from the service, instead the service deals in representations. A representation is a particular format for a resource. Some representations for a webcam might be an HTML document that provides some information about the webcam or a jpeg image file that is the most recent image captured from the webcam. Two common representations, and the ones supported by RestUpMVC, are JSON and XML.

Resouces

Exposing a resource from a RestUpMVC service involves three steps; create the resource, create a controller to handle requests for the resource, and register the resource with the framework. By following some simple conventions, manual configuration is minimized. The best way to learn how to expose resources is by showing some examples.

Exposing a simple resource

The following is an example of a resource that could be exposed from a project management service:
public class Project {
    public int ID { get; set; } 
}

You would expose this resource with a controller like this:
//the controller should be named {resource}Controller
public class ProjectController : Controller
{
    //would map to an HTTP GET request to /project/
    public ActionResult List()
    {
        //return list of projects
    }
    //would map to an HTTP GET request to /project/{id}
    public ActionResult Get( int id )
    {
        //return single project
    }
    //would map to an HTTP POST request to /project/ and would expect a representation of project in the request body
    public ActionResult Post( Project project )
    {
        //create a new project
     }
    //would map to an HTTP PUT request to /project/{id} and would expect a representation of project in the request body
    public ActionResult Put( Project project ) 
    {
        //update the project
    }
    //would map to an HTTP DELETE request to /project/{id}
    public ActionResult Delete(int id)
    {
        //delete the project whose ID = id
    }
}
The controller example above makes use of the following conventions:
  • the controller name starts with the name of the resource, in this case the resource is called Project so the controller is ProjectController
  • the controller uses specific action method names which map to specific URI pattern and HTTP method combinations. The following table shows the mapping between the controller action names and the URI and HTTP method combination:
Action method name maps to request should perform the action
List() GET /project/ gets a list of Projects
Get( int id ) GET /project/id gets the Project by ID
Put( int id, Project project ) PUT /project/id updates the project
Post( Project project ) POST /project/ creates a new project
Delete( int id ) DELETE /project/id deletes the project
  • the controller actions Get( int id ) and Put( int id, Project project ) use the name of the resource's unique identifier property as the name of the argument that will have the id value mapped to it during a request. In this case, the Project's unique identifier is called ID and the name of the method argument is id, notice this is not case sensitive. By default RestUpMVC expects resources to have a property called ID to represent their unique identifier values. This convention can be overridden.

Finally, register the resource at application start:
protected void Application_Start()
{
    RestUpMvcConfiguration.Instance.RegisterResource( typeof(Project) );
}

Representations

Request

Currently the framework supports sending and receiving representations of resources formatted in either XML or JSON. The framework can determine the format of the representation by examining the Content-Type request header. For example, if you wanted to create a new Project resource by sending an XML representation you would execute a request such as this:
POST /api/project HTTP/1.1
Host: www.example.com 
Content-Type: application/xml

<project>
    <name>My New Project</name>
</project>

A JSON formatted request would look like:
POST /api/project HTTP/1.1
Host: www.example.com 
Content-Type: application/json

{
    name: "My New Project"
}

Response

The client can choose which representation of a resource they want to receive by sending the Accept HTTP header. Both XML and JSON are supported by default. To receive the resource formatted as XML the client would send a request like this:
GET/api/project/1 HTTP/1.1
Host: www.example.com 
Accept: application/xml

The response would be:
HTTP/1.1 200 OK
Content-Type: application/xml

<project>
    <id>1</id>
    <name>My New Project</name>
</project>

Similarly, requesting a JSON formatted representation:
GET/api/project/1 HTTP/1.1
Host: www.example.com 
Accept: application/json

The response would be:
HTTP/1.1 200 OK
Content-Type: application/json

{
    id: 1,
    name: "My New Project"
}

Response Codes

Return the correct response code from your controller.
public ActionResult Get(int id)
{
    var project = //get the project
    return this.RestOK(project);
}
200 OK - The 200 OK status should be returned when an operation has succeeded such as when retrieving a list of entities.

201 Created - The 201 Created status should be returned whenever an new resource is created. The URI for the new resource will be included in the HTTP Location header.

Last edited Feb 16, 2011 at 10:18 PM by Broncanus, version 9

Comments

No comments yet.