I was recently asked to provide some basic notes on what an API is and why one might want to develop or work with them. Having embarked on my own exploration of the topic only a few months ago, the following thoughts are probably naive and certainly incomplete. But they’re my current first-order approximation of an answer to the question, “why an API?”
An API is a set of commands that a program or application provides (exposes) that, when submitted to that application, instruct it to do something, or alter the way it does something. The important thing is that these aren’t commands in the sense of mouse clicks or typed instructions, but are meant to be submitted by other applications, known as clients. An API is an interface, that allows one program to interact with another.
This permits a few distinct but related features for an application.
First, each application is concerned with its own business. It doesn’t need to do everything. Its authors don’t need to conceive of every possible use of the data it stores or the features it provides.
Second, to anything outside an application, it’s a black box. How it goes about its business is its own problem. It doesn’t matter what language it’s programmed in or what specific kind of database it uses. And of course the same thing is true of the application using the API.
Third, and most importantly, interaction with and use of the API, and therefore of the underlying application, can itself be programmed. It can be automated. Data retrieved from it can be acted on by other applications to other purposes. Entirely new applications can be written around it, with their own processes and interfaces and so on.
Now, there are a number of different kinds of APIs. A programming framework is an API. At heart, Drupal is basically an API. It provides a variety of functions that do complex things, such as displaying forms and accessing a database, which a programmer can employ to provide interaction for a web user.
But what most people mean when they use the term API is specifically a REST API… a set of URLs provided by a website which, when requested, usually cause an underlying application to act on data in some way.
That these are URLs adds a fourth feature to an application… it doesn’t have to run on the same machine as the client. It doesn’t even have to be in the same environment, or network, or in any kind of proximity whatever. It’s on the net, and anyone can write a program to interact with it from anywhere else on the net.
This transforms the application from a standalone program that has to be downloaded, installed, and run into a service. The application is now the seed of an ecosystem – a modular, distributed network of programs that interface with the core application, each providing its own style or means of user interaction, each performing its own particular operations on the data flowing into and out of the service, each in effect extending the application itself… though still within the constraints dictated by what capabilities its API exposes.
Finally, since the API is an interface, and not the actual application itself, changes can be made to the application without breaking the operation of the clients interacting with it. As long as the API remains consistent – as long as visiting a particular URL with the proper credentials in hand can be trusted to produce known results – the internals of the application can be altered even to the point of changing the programming language it’s developed with.
The canonical example of all this is Twitter. Twitter itself is a fairly straightforward application. It stores text data, ordered by date and organized by association with its authors. But Twitter exposes an API which allows one access, not only to methods to read and write those posts, but to the metadata associated with them (information about the data, such as dates and flags and so on), allowing a programmer to develop all kinds of ways of examining the social network it represents… ways which Twitter itself may have no interest in developing.
So. The components are all in place and nicely separable. An application (or service) is a program that stores, provides, and manipulates data about a domain of information… news, photos, people, messages, money, etc. An API (specifically a REST API) is an internet-accessible programming interface that enables the transfer of data and metadata into and out of the application, and usually to exercise features of the application itself. And a client is a completely independent program that makes use of the API to do whatever one might care to with that data and those features.
It all makes for a very powerful way of doing things. The population of people who can come up with things to do with the data and features is now as large as the population of programmers who care to interact with the API. The core application itself now doesn’t have to perform every conceivable function, but only do one thing well, and provide carefully designed access to that one thing. And any component of the ecosystem can be swapped out or upgraded without interfering with the functioning and utility of the whole.