What is an API?
APIs - or Application Programming Interfaces - are defined as a set of functions (a coded procedure performing a particular task) through which two software can talk to each other without any human intermediation. An API is an abstracted point of entry to a piece of software with a description of the open interface and its behavior.
Let’s break that acronym down:
- Application: By application, we mean a service with which a developer wants to interact. This service can be a stream of meteorological data, an image sharing app or an open data portal.
- Interface: The interface is the entry door to the service. You have to go through that door to interact with the service capabilities (e.g., filtering meteorological data for a city, publishing pictures on Instagram…)
- Program: The program is a set of coded procedures written by a developer. The program is designed to interact with the application, so we don’t have to. For example, the program can submit a postal address to get coordinates (think Airbnb or Google Map).
To sum it up: APIs are programs using a specific point of entry (the interface, also call an end-point) to interact with an application (or some features within this application).
APIs can easily be understood using the electricity network as a proxy
Let’s start with an electricity supplier:
- this supplier produces and distributes a service: electricity
- to distribute this service, the supplier relies on infrastructure: the electric network (stations, transmission lines, utility poles, sockets)
Now, let’s take a lamp that needs to consume electricity:
- for the lamp to work, it needs to be connected to the electric grid
- to be connected, the lamp is sold with a plug that fits standards sockets
The socket is a standardized point of entry (an interface) through which a lamp consumes electricity. An API is a standardized point of entry (an interface) through which a program consumes an application.
APIs allow developers to delegate a service they need to consume. In the same way, the lamp’s owner delegates the electricity needed by her lamp to the electricity supplier.
Let’s dig further. APIs and electrical sockets both specify how the user can consume the service. Remember our lamp? It needs to respect some conditions for using the service:
- the number and shape of the pins
- voltage and frequency
- type of current
- etc…
APIs will do the same and specify conditions to use them:
- number of API calls for a defined lap of time
- what you can expect to do: read and/or write
- etc…
Thanks to the standardization of sockets, you can plug several lamps in your home without thinking twice about it. What matters is that every socket is functionally similar: it brings electricity right into your home.
Web APIs
Web APIs are APIs that can be accessed using the HTTP protocol. The API defines endpoints, and valid request and response formats. Web APIs include the APIs used to communicate with the browser (see list). They may be services such as web notifications and web storage. Different web APIs feature varying levels of security and privacy, including open, internal and partner APIs. Multiple web APIs can be combined into a composite API - a collection of data or service APIs.Open APIs
Open APIs, also known as external or public APIs, are available to developers and other users with minimal restrictions. They may require registration, and use of an API key, or may be completely open. They are intended for external users (developers at other companies, for example) to access data or services. As an example, take a look at the provided by the UK government. Any developer can access it, without even registering, allowing app builders to include governmental data on restaurant standards in their apps.Internal APIs
In contrast to open APIs, internal APIs are designed to be hidden from external users. They are used within a company to share resources. They allow different teams or sections of a business to consume each other’s tools, data and programs. Using internal APIs has several advantages over conventional integration techniques, including security and access control, an audit trail of system access, and a standard interface for connecting multiple services.Partner APIs
Partner APIs are technically similar to open APIs, but they feature restricted access, often controlled through a third-party API gateway. They are usually intended for a specific purpose, such as providing access to a paid-for service. This is a very common pattern in software as a service ecosystem.Composite APIs
Composite APIs allow developers to access several endpoints in one call. These could be different endpoints of a single API, or they could be multiple services or data sources. Composite APIs are especially useful in microservice architectures, where a user may need information from several services to perform a single task. Using composite APIs can reduce server load and improve application performance, as one call can return all the data a user needs.Different Types of API Architectures and Protocols
- REST
- JSON-RPC and XML-RPC
- SOAP
REST
REST (representational state transfer) is a very popular web API architecture. To be a REST API, an API must adhere to certain architectural constraints, or principles, including:
- Client-server architecture: the interface is separated from the backend and data storage. This allows for flexibility, and for different components to evolve independent of each other.
- Statelessness: no client context is stored on the server between requests.
- Cacheability: clients can cache responses, so a REST API response must explicitly state whether it can be cached or not.
- Layered system: the API will work whether it is communicating directly with a server, or through an intermediary such as a load balancer.
JSON-RPC and XML-RPC
An RPC is a remote procedural call protocol. XML-RPC uses XML to encode its calls, while JSON-RPC uses JSON for the encoding. Both protocols are simple. A call can contain multiple parameters, and expects one result. They have a couple of key features, which require a different architecture to REST:
- They are designed to call methods, whereas REST protocols involve the transfer of documents (resource representations). Or, to put it another way, REST works with resources, whereas RPC is about actions.
- The URI identifies the server, but contains no information in its parameters, whereas in REST the URI contains details such as query parameters.
SOAP
SOAP (simple object access protocol) is an established web API protocol. It is intended to be extensible, neutral (able to operate over a range of communication protocols, including HTTP, SMTP, TCP and more), and independent (it allows for any programming style) The SOAP specification includes:
- The processing model: how to process a SOAP message.
- Extensibility model: SOAP features and modules.
- Protocol binding rules: how to use SOAP with an underlying protocol, such as HTTP.
- Message construct: how to structure a SOAP message.
Note that it is possible to build a RESTful API while using SOAP protocols, although the two are usually considered to be competing standards.
