Application Programming Interface (API) is a piece of software that allows applications to communicate and transfer resources. There are different types of APIs, notably SOAP (Simple Object Access Protocol) and REST (REpresentational State Transfer). Regarding REST, there are strict and pragmatic views of what qualifies as a RESTful API. Strict REST proponent would say that an API can only be considered RESTful if it satisfies all the constrains of the REST architectural style defined by Roy Fielding in his doctoral dissertation. REST pragmatist are more relaxed about these constrains. Many web APIs are not strictly speaking RESTful API. They might meet some but not all the constrains. Roy Fielding himself has shown frustration about people refer to their APIs as RESTful without meeting all the constrains. In this post, we will take a more pragmatic view of REST APIs (simply refer to them as web APIs). We will explore how they work and why we might benefit from using them.

How an API works

As HTTP is the primary protocol used on the web, most web APIs build on HTTP. As long as a client can generate HTTP requests and parse HTTP responses, they can interact with the API. This way, the API can take advantage of the set of HTTP methods (GET, PUT, POST, DELETE) to perform CRUD operations on resources. Meaningful HTTP status code can also be used in API responses (200 - OK, 404 - Not Found, etc…) These are well established conventions that everyone on the web is familiar with. In fact, it is a good API design principle to follow these HTTP verbs and status codes while building an API.

The purpose of web APIs is to facilitate data communication and resources transfer between one application and another. Therefore, APIs are designed around the data they provide to their clients. Each piece of data (or resource) that an API exposes to the world need to have an unique identifier which is the URI (or endpoint). Clients can then reach these URIs to request certain operations to be perform on the resources. This collections of endpoints, each one represent a resource, is one key characteristic of REST APIs. If a client needs information from multiple resources, they have to send multiple requests to the relevant endpoints to piece together the data they need.

Suppose we have a tictactoe tournament and we need an API to help clients retrieve and update statistics on the games and the players. These are a few example endpoints and operations to perform on them.

GET /games - Retrieves information on all completed games
GET /games/15 - Retrieves information on a specific game (id 15)
POST /games - Create a new game
PUT /games/8 - Updates the status of game id number 8
DELETE /games/10 - Delete game id number 10

GET /players - Retrieves information on all players
GET /players/3 - Retrieve info about player id 3
POST /players - Create a new player
PUT /players/9 - Update the status of player id 9
DELETE /players/5 - Delete player if number 5

A request to obtain info on game id 15 would look like this:

GET http://tictactoe.com/games/15 HTTP/1.1

In order to send data to a client, the API needs a format to represent that data. Many web APIs use JSON - JavaScript Object Notation. JSON is compact, light-weight and interface well with Javascript-based web apps. However, XML or YAML would be acceptable formats as well.

A response in JSON format for the GET request above might look like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "GameId": 15,
  "Status": "Completed",
  "Winner": "X"
}

The benefits of APIs

API’s set the stage for how code interfaces or communicates with other code. They provide the necessary building blocks to cleanly put together different software components of an application to make it work as a whole. Well defined functions or end points (in case of a web application) in an API simplify a lot of details for users by clearly listing out the core functionality and behavior of the underlying application. This helps with building robust and stable applications with predictable behavior.

As a concrete example, consider the Foursquare places API. This API gives users access to Foursquare places database. Many applications rely on this API for venue searching and geo-tagging. The API is well documented with clearly defined end points, the allowed operations on these end points and their response structure. The API is broken down by functionality (i.e Venues, Photos, Tips etc) which makes it very convenient for a client application to quickly access the information it needs.

Imagine if Foursquare did not have this API and instead exposed it’s codebase for developers to use. If you as a user now wanted to query the Foursquare database for a listing of Venues or Location Tags, how would you do it? . Well, you would have to spend quite a bit of time exploring the codebase trying to fish out the methods and functions which will help you with retrieving that information. This is quite tedious and labor intensive. Even after you figure it out and write your application referencing the Foursquare code in order to obtain the data you need, the pain does not end there. What if next month, Foursquare makes changes to their codebase and the internal functions and methods your application relied on are no longer valid?. You would have to go through the same treasure hunt through the code base as before to find out the new methods and functions you now need to use. This makes your client application fragile and not really sustainable.

API’s provide an abstraction layer that allows the underlying logic to change or extend without interfering with the exchange of data between server and clients. As long as the API stays the same, the server and its clients can interact with each other. This allows the client application and the server application to evolve independently. That’s the benefit of using an API.