Rest Resources, HTTP Methods and Status Codes

Introduction

REST stands for REpresentational State Transfer. We use REST while doing web services programming to communicate between client and server. There are many concepts involved in the REST world that are required to know for building a RESTful service. We will have a look at some of those building blocks of RESTful service here.

Resources

Everything in REST is a resource. It can be a document, an image, a collection of objects, information stored in the database, etc. REST requires a Unique Resource Identifier (URI) associated with each resource for it to be accessible over the internet. URI is the endpoint of a given resource.

The state of each resource is also an important factor while accessing it. The client-side can use the resource in the best possible way when it knows the type and state of the resource. So REST responses will have a machine-readable explanation about the resource. That is a resource representation. It can be the details of the resource, its format, size, etc.

REST and HTTP

We saw resources can be of any type, but there are some rules in the REST world while interacting with resources. REST requests and responses use the HTTP protocol. There are specific HTTP message formats that REST clients have to follow while sending a request. The response from the server also will be in a certain message format that a REST client can decode.

There are eight different message formats that HTTP has defined. The following are the commonly used four methods.

1. GET: Get a representation of a given resource.
2. DELETE: Destroy the specified resource.
3. POST: Create a new resource, based on the given representation.
4. PUT: Update the state of a given resource with the one described in the given representation.

The main aspects of choosing these methods are because of its adherence to the REST specification (RFC 2616). The two main properties in RFC 2616 are safety and idempotency.

Safety here means the ability of the client to make requests without altering the state of a given resource. Idempotency means the effect of doing an operation will be the same for single or multiple times.

Request Response Structure

Now we will see how these methods are used in an HTTP request and response in a RESTful way.

A REST client library will create a REST API request in the following format:

The API response, in turn, will have the following format:

Following is a sample GET request:

Method: GET

URL: http://api.clothshop.com/shirts

Which will provide the following response:

 HTTP/1.1 200 Content-Type: application/json { “id”: 10, “name”: “Lee Shirt”, “color”: “yellow”, “price”: “$30” }

HTTP Status Codes

Whenever we do a REST API request to the server, the server will return a response with an HTTP status code. Each status code will tell a brief about the response from the server. These status codes will be part of the HTTP header which the client will decode and understand. These are wrapped with HTML code and all HTML /HTML5 browsers are capable of understanding these HTTP codes.

The following table summarizes the major status codes and their meaning.

Summary

 There are multiple building blocks in the REST framework that makes web services communication happen over the internet. HTTP protocol is one of the main blocks upon which the entire REST communication is built. While designing a REST API it is important to consider the nature of resources that we are planning to expose as APIs. Also it is important to know various HTTP methods and status codes that will help us in the process of accessing these resources at the client side.