Tuesday, April 7, 2015

Introduction to RESTful APIs

REST, or REpresentational State Transfer, is a set of design principles and best practices for designing "RESTful" systems. Since it was first introduced by Roy Fielding in his 2000 doctoral dissertation, it has solidified a standard for how many software applications communicate through APIs. API stands for Application Programming Interface and it's usually a set of endpoints (/login, /update, etc.), functions, or events to listen for through eventlisteners, that allow two pieces of software to communicate. But while APIs bridge all types of software together (client to client, client to server, server to server, etc.), REST is mainly concerned with client to server communication over HTTP.

You may also think of REST as an architectural style, as opposed to a concrete thing. REST is not the system itself, but the characteristics and properties of that system that make it distinctly RESTful. By respecting the constraints of this style, you'll be able to capitalize on performance and scalability gains, as well as make your system simpler to manage. Now before we continue with REST, let's learn a little bit about HTTP.


In it's simplest form, HTTP is a request response protocol[1], with the request originating from the client and the response being returned from the server. Now, the client can be a browser, mobile or desktop application and HTTP allows your client to appear as if it's communicating directly with the server. The REST architecture style was developed in tandem with HTTP/1.1 based on the existing specifications of HTTP/1.0. At this point, REST is widely supported, governing the interactions between origin servers, gateways, proxies and clients.

A Typical GET Request

Let's run the following command in the terminal, and examine the HTTP request headers: curl -iv https://reddit.com/r/videos.

GET /r/videos/ HTTP/1.1
User-Agent: curl/7.37.1
Host: www.reddit.com
Accept: */*

The request was to a resource identified by the uri www.reddit.com/r/videos, which is composed of the Host and GET path. GET is known as the method and the HTTP/1.1 specification defines others as well.

Safety and Idempotency

Safety and Idempotency are two important properties of the specification. Safe methods, such as GET and HEAD, should never change the resource representation. This also means that safe methods can be cached and prefetched without any consequences to the resource. Idempotent means the result is always the same, whether the method is called once or multiple times, and is important for building fault-tolerant APIs. For example, executing x = 5 gives you the same result every time, but x += 1 does not. So when using idempotent methods, if they fail or take a while to carry out, it's safe to call them multiple times until we get a response from the server.

Method Idempotent Safe
GET Yes Yes
HEAD Yes Yes
PUT Yes No

A Typical Response

This is the response from that same GET request which contain the header and a portion of the response body. Response headers contain status codes, as well as control data. For example, cache-control, which indicates whether or not or how long the response can be cached.

HTTP/1.1 200 OK
Date: Mon, 06 Apr 2015 21:02:19 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: __cfduid=d217c17620070ff3c4d04776bb08768011428354139; expires=Tue, 05-Apr-16 21:02:19 GMT; path=/; domain=.reddit.com; HttpOnly
cache-control: no-cache
<!doctype html><html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">

REST Characteristics

Just like any specification or style, REST provides it's own set of features and constraints. A few of them are as follows:

  • Stateless
  • Layered system
  • Cacheable
  • Uniform interface
  • Client-Server

So when we say REST is stateless, we mean that each request is independent of others, allowing intermediaries to work on a single interaction without having to understand the entire topology. So when you make a request to authenticate, the server shouldn't store a state that indicates that session is authenticated. You should instead send each subsequent request with a token, for example.

Layering allows intermediaries to include themselves throughout the request response path without affecting the interfaces between components. This is why it's especially important that the communication is stateless.

REST responses are also cacheable, allowing for efficiency and performance benefits, not having to request the server every time a resource needs to be fetched. The request will simply access the cached resource, instead.

And by uniform service, we're referring to resources that are defined by the paths in the URI and the limited number of methods (GET, PUT, POST, etc.)

REST vs. SOAP vs. oData

A service architecture A service architecture A protocol
XML, JSON (recommended), YAML, HTML, other XML recommended JSON, Atom
Open source Open source Microsoft implemented, open source
Slower than REST Faster than SOAP
More mature than REST Less mature than REST, but RESTful by design


1. ^ An agreed upon format for data exchange within or between computers.

No comments:

Post a Comment