Getting to know HTTP

Since we concluded in the previous section that Web APIs are based on HTTP, it is important to understand some of the fundamental constructs of HTTP before we delve into other details.

THE RFC 26163 specification published in June 1999 defines the Hypertext Transfer Protocol (HTTP) Version 1.1. The specification categorizes HTTP as a generic, stateless, application-level protocol for distributed, collaborative, and hypermedia information systems. The role of HTTP, for years, has been to access and handle especially when serving the Web documents over HTML. However, the specification allows the protocol to be used for building powerful APIs that can provide business and data services at hyperscale.

Note

A recent update to the HTTP 1.1 specification has divided the RFC 2616 specification into multiple RFCs. The list is available at http://evertpot.com/http-11-updated/.

An HTTP request/response

HTTP relies on a client-server exchange and defines a structure and definition for each request and response through a set of protocol parameters, message formats, and protocol method definitions.

A typical HTTP request/response interaction looks as follows:

The client made a request to fetch the contents of a resource located at www.asp.net, specifying to use HTTP Version 1.1 as the protocol. The server accepts the request and determines more information about the request from its headers, such as the type of request, media formatting, and resource identifier. The server then uses the input to process the results appropriately and returns a response. The response is accompanied by the content and a status code to denote completion of the request. The interaction between the client and server might involve intermediaries such as a proxy or gateway for message translation. However, the message request and response structures remain the same.

Note

HTTP is a stateless protocol. Hence, if we attempt to make a request for the resource at the same address n times, the server will receive n unique requests and process them separately each time.

HTTP methods

In the preceding request, the first thing a server needs to determine is the type of request so that it can validate if the resource supports this request and can then serve it. The HTTP protocol provides a set of tokens called methods that indicate the operations performed on the resource.

Further, the protocol also attempts to designate these methods as safe and idempotent; the idea here is to make the request execution more predictable and standardized:

• A method is safe if the method execution does not result in an action that modifies the underlying resource; examples of such methods are GET and HEAD. On the other hand, actions such as PUT, POST, and DELETE are considered unsafe since they can modify the underlying resource.
• A method is idempotent if the side effects of any number of identical requests is the same as for a single request. For example GET, PUT, and DELETE share this property.

The following table summarizes the standard method definitions supported by HTTP Version 1.1 protocol specification:

Method	Description	Safe	Idempotent
OPTIONS	This represents the communication options for the target resource.	Yes	Yes
GET	This requests data from a specified resource.	Yes	Yes
HEAD	This is the same as GET, but transfers only the status and header back to the client instead of the complete response.	Yes	Yes
POST	This requests to send data to the server, typically evaluates a create request.	No	No
PUT	This requests to replace all current representation of the target resource, typically, generally evaluates an Update request.	No	Yes
PATCH	This applies a partial update to an object in an incremental way.	Yes	No
DELETE	This requests to remove all current representation of the target resource.	No	Yes
TRACE	This performs a message loop-back test (echo) along the path to the targeted resource.	Yes	Yes
CONNECT	This establishes a tunnel to the server identified by a given URI. This, for example, may allow the client to use the Web server as a proxy.	Yes	Yes

HTTP status codes

HTTP status codes are unique codes that a server returns based on how the request is processed. Status codes play a fundamental role in determining response success and failure especially when dealing with Web APIs. For example, 200 OK means a generic success whereas 500 indicates an internal server error.

Status codes play a pivotal role while developing and debugging the Web API. It is important to understand the meaning of each status code and then define our responses appropriately. A list of all HTTP status codes is available at http://en.wikipedia.org/wiki/List_of_HTTP_status_codes.

Other HTTP goodies

From a Web API perspective, there are some other aspects of HTTP that we should consider.

Header field definitions

Header fields in HTTP allow the client and server to transfer metadata information to understand the request and response better; some key header definitions include:

Field	Description
Accept	This specifies certain attributes that are acceptable for a response. These headers can be used to provide specifications to the server on what type of response is expected, for example, Accept: application/json would expect a JSON response. Note that as per the HTTP guidelines, this is just a hint and responses may have a different content type, such as a Blob fetch where a satisfactory response will just be the Blob stream as the payload.
Allow	The header indicates a list of all valid methods supported by a requested resource (GET, PUT, POST). It is just an indication and the client still may be able to seek a method, not from the Allow list. In such cases, the server needs to deny access appropriately.
Authorization	This is the authorization header for the request.
Content-Encoding	The header acts as a modifier to a content type. It indicates the additional encodings that are applied to the body, for example, Gzip, deflate.
Cache-Control	This indicates a cache directive that is followed by all caching mechanisms throughout the request/response chain. The header plays an important role when dealing with server-side cache and CDN.
Content-Type	This indicates the media type of the entity-body sent to the server.
X-HTTP-Method	The header allows clients or firewalls that don't support HTTP methods such as PUT or DELETE to allow these methods. The requests tunnel via a POST call.

Content negotiation

Content negotiation is a technique to identify the "best available" response for a request when multiple responses may be found on the server. HTTP 1.1 supports two types of negotiations:

• Pre-emptive or server-driven negotiation: In this case, the server negotiates with the client (based on the Accept headers) to determine the type of response.
• Reactive or client-driven negotiation: The server presents the client with the representations available and lets the client choose based on their purpose and goals.

More information about content negotiation can be found at http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html.