What is a Web API? APImetrics Explains it All

“What is a web API?” At APImetrics, we actually get this question a lot. And I found someone asking this question recently on Quora as well. I answered it there, and I thought it’d be helpful to post it here, too. Happy learning!

To understand what a web API is, it’s necessary to understand what makes a HTTP request to an API different from a HTTP request to any old URI (Universal Resource Indicator, which typically might be a webpage).

Generally, we might expect that a HTTP server will return HTML. After all, it is the Hypertext Transfer Protocol. But an API will, in 2017, typical return its payload in JSON (JavaScript Object Notation) format. JSON is a format for exchanging structured data in a compact, but human-readable format. In order to do anything with the JSON payload, the client that made the HTTP request to the API must know the way that the JSON is structured. It can then extract the information returned, process it as necessary and display in the browser or app.

An example might be an insurance price comparison website. I make a request from my browser to the price comparison website. This request will contain all sorts of information about myself such as my age, address, type of car, number of years of no-claims. The price comparison site then sends that information on to to dozens of actual insurance providers, which then return the actual quotes.

Now, in the ancient days of the web those quotes might have been in HTML format and the information the price comparison site needed would have to be scraped painfully out of the HTML. These days the insurance providers send the quote back in a pre-agreed JSON format.

It’s not as though the price comparison site needs to render each quote in a browser. The price comparison site then munges all the quotes together probably into another block of JSON that it can then squirt back to me where the list of quotes can rendered as a nicely formatted table in the price comparison webpage on my browser or in the price comparison app.

So APIs are really great for plumbing together all sorts of back offices functions and services, both inter-business and intra-business, which is one of the reasons why they have become so popular over the last few years.

Of course, the request to the API doesn’t have to be returned in JSON. It could be returned in XML (Extensible Markup Language), which is more verbose than JSON, but possibly to a degree more self-documenting, or unstructured plaintext or binary or even HTML (which is just a form of XML). So another defining characteristic of what makes an API is the notion that the server is going to do some work with the information in the request it receives.

I am going to provide some URI parameters or information about exactly what data I want in the HTTP headers. It is not just a case of making a request to return a static HTML page. That wouldn’t be an API. Instead I am requesting a taxi to take me from my office to Liberty on 15th Avenue E in Capitol Hill.

Each request to the ride service server is different and a lot of back office processing will probably be needed before it send back all the data I need to me. The documentation for an API will specify the endpoints (the URIs the HTTP requests are send to), the various parameters than can be sent (for instance, my location and destination) and the form of the response.

Most APIs are REST (Representational state transfer) APIs (or claim to be). You can read about the characteristics of REST on the FoAK (Fount of All Knowledge), but probably the most interesting one is statelessness.

All of the information the server needs to satisfy my request should be included with the request. (In practice, there are ways of handling state.) So, for instance, if I want to know my bank balance, I have to send some information to the API in my request that allows the server to identify the customer the request is from. There are many schemes for securely authorizing and authenticating users of an API. A popular one is OAuth2.

A typical API request looks like this


and the returned JSON looks like this

  1. {“query”:{“count”:1,”created”:”2017-05-12T23:04:12Z”,”lang”:”en-GB”,”results”:{“channel”:{“item”:{“condition”:{“text”:”Scattered Showers”}}}}}}

Normally, some client-side processing would extract the pertinent information from the JSON and display it in an attractive form that is easy for the end user to digest.

So when people talk about a web API, there are many things that they might be referring to, but they are probably referring to a set of URI endpoints that take various parameters and return some payload to the requester, very often in JSON format. And APIs are important because they are great way to help bolt together systems that need to need to exchange information in standardised ways.

Photo by Richard Pope