Basics of Web API and REST

ASP.NET Web API is a framework built by Microsoft, which makes it easy to build HTTP services (REST) that reach a broad range of clients, including browsers and mobile devices. With Web API, if the client is requesting the data to be returned as JSON or XML, the Web API deals with the request type and returns the data appropriately based on the media type.

Web API is an ideal platform for building pure REST services where the request and response happens with HTTP protocol. The client can make a GET, PUT, POST, and DELETE request and get the response appropriately.

Before we go deep in Web API, let’s understand the concept of REST.

What is REST (Representational State Transfer)?

According to Wikipedia:

Representational state transfer (REST) is an abstraction of the architecture of the World Wide Web; more precisely, REST is an architectural style consisting of a coordinated set of architectural constraints applied to components, connectors, and data elements, within a distributed hypermedia system. REST ignores the details of component implementation and protocol syntax in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements.

We can define REST as an architectural style that sits on top of HTTP principles. Growth of REST in last few year is fastened to the API design because most web application offer to expand their functionality. HTTP come up to fit excellently with the REST principles.

The principles of REST

Stateless

It is a fundamental principle for a REST application; the server should never store information about the clients. This means that when a request comes to the server, the server loads the resource from database and sends back the representation to the client.

Stateless also means that the server should never use sessions or other mechanisms to store client information, and every request is not correlated with past or future requests.

Uniform Interface

Heart of REST are the resources, which we want to manage using the API. Individual resources are identified in requests, for e.g. using URIs in web-based REST systems. The resources themselves are conceptually separate from the representations that are returned to the client. A resource could be a customer details, a document, and in general, anything that we want to expose.

While requesting to the resources with URI, we obtain representation of that resources in particular format. The format is negotiated and could be anything from the XML and JSON, or other binary formats.

Cacheable

The client can cache the resource, and the server should provide information about the cacheability of the resource itself. Well-managed caching partially or completely eliminates some client–server interactions and improving scalability and performance.

Client-Server

A uniform interface separates clients from servers, means what the client sees is the URI and the representation of the resource, that’s all. The client can’t see where the resource is stored. This separation of concerns means that, for example, clients are not concerned with data storage, which remains internal to each server, so that the portability of client code is improved. Servers are not concerned with the user interface or user state, so that servers can be simpler and more scalable.

Layered System

The client knows very little about the server; it doesn’t know, for example, if it is directly connected to the server or if it arrived at the server by passing through a proxy or other intermediary server (balancer, etc.).

HTTP verb used by Web API

We are used to GET and POST since the browser manages these two verbs, but others are specified in the HTTP specification (RFC 2616) that can be used for other operations.

The complete list of verbs is: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE, and CONNECT. These verbs should by used with their semantic meaning, for e.g. we need to create a resources use POST method, and when we need to read the resources we use GET method and so on.

HTTP verb used by Web API and their meaning
HTTP Verb URI Meaning
GET /values Get all values
GET /values/10 Get the value with id=10
POST /values Create a new value
PUT /values/10 Update the value with id=10
DELETE /values/10 Delete the value with id=10
GET

To read a resource we use GET method. Along with URI of resoursce we can use ACCEPT header to ask for specific header.
For example, if we instruct server to return Content of values in JSON format we can use:

GET /posts HTTP/1.1 
Accept: application/json
POST

We use POST method to create a resource, the resource data is sent to the server along with the request’s body.

PUT

To modify the resource PUT method is used. The URI specifies the resource that we want to modify and the body contains the new resource values.

DELETE

DELETE is used to delete the resource.

A hope

I hope that you will have better understanding of Web API and REST. I would like to hear valuable feedback or question from you. It encourage me to write more quality article.

Happy Reading 🙂

Advertisements

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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