How do APIs work?

How do APIs work?

Application programming interfaces (APIs) allow software programs to communicate with each other by sending and receiving API calls, or requests for information. These requests are initiated by an API client and accepted by an API endpoint.

In order to exchange information between APIs, developers must provide API documentation that describes the types of requests an API can accept, the use cases it is designed to support, and any other conditions (e.g. protocols, schemas, and security requirements) that third parties are required to follow.

API calls allow APIs to share functionalities without requiring developers to rewrite functions from scratch for each individual application. Without them, developers would not be able to easily replicate functions across multiple applications or request data from other apps, services, and providers.

What is an API?

An API is an interface that enables software programs to share data and functions. This method of communication helps enhance the functionalities of most modern web applications.

For example, imagine that Alice develops an application that customizes classical music playlists to listeners’ moods. Instead of manually inputting thousands of tracks to populate these playlists, she can use an API that connects to an external music repository — saving time, money, and development challenges by doing so.

The use cases for APIs are nearly limitless. They connect cloud services, query databases, auto-update mobile applications, stream content to multiple devices, aggregate flight prices and food delivery options, and so much more.

What is an API client?

An API client, sometimes called a “user,” is the software that initiates an API call.

Before it can interact with an API endpoint, an API client needs to verify its identity. This helps prevent attackers from exploiting APIs to perform distributed denial-of-service (DDoS) attacks or other malicious actions.

Typically, authentication is carried out via one of four methods: a unique string of characters (API key), a username and password combination, an OAuth token, or mutual TLS. Using a strong authentication method is one of the ways developers can safeguard APIs from attacks. (Learn more about API security.)

What is an API endpoint?

An API endpoint accepts the API call and returns the requested information.

Both API clients and endpoints refer to software programs hosted on servers rather than discrete hardware devices. API servers may host multiple endpoints — each of which is assigned a uniform resource identifier (URI) that allows it to be located by an API client. In most cases, this URI is a uniform resource locator (URL), which points to Internet-based locations (e.g. a website).

What is an API schema?

An API schema is metadata that defines the specifications an API request must meet in order to be considered valid. These specifications may include details including the target endpoint, HTTP method, and other requirements established by developers.

When an API call is sent from a client, it must meet the conditions outlined in the schema. Only then can an API endpoint return the requested information. To put this into perspective, imagine that Bob is planning a party. On the invitation, he specifies that only guests who bring yellow daisies will be given thank-you cards after the party. If, however, Carol decides to bring red roses to the party, she will not receive a thank-you card afterward.

Similarly, an API call that does not fulfill the requirements set by the API schema will not receive a response.

What is an API?

Like APIs themselves, API calls vary according to the specifications outlined in the API documentation. Generally speaking, however, an API call follows three basic steps:

1. The API client initiates the API call, or request for information. The API client must format the request according to the protocol and schema provided by the API endpoint.
2. The API endpoint receives the request. The API endpoint then authenticates the API client and validates the API schema. This helps ensure that a) the call is coming from a verified source, and b) the conditions of the request have been met.
3. The API endpoint returns the requested information to the API client. The API schema determines the type of responses that may be returned to the client.

For a more in-depth explanation of API calls, read What is an API call?

What protocols and architectures do APIs use?

APIs are supported by several different protocols. A protocol is a method of communicating over a network; it tells the API how to format requests and responses. The type of API protocol used depends on the purpose for which the API has been developed, the use cases it serves, and the restrictions it carries.

The two most common API protocols are simple object access protocol (SOAP) and remote procedural call (RPC). Representational state transfer (REST) is a software architecture that is often compared to these protocols.

SOAP provides a standardized method of sending and receiving calls between APIs that use different operating systems and architectures. It is also compatible with the hypertext transfer protocol (HTTP), file transfer protocol (FTP), simple mail transfer protocol (SMTP), and other application layer protocols. It can only return data to API clients using extensible markup language (XML).

RPC is one of the simplest and oldest methods of communicating between APIs. It works by initiating a remote procedural call, during which a client requests a function from a remote server. The primary difference between RPC and SOAP/REST is that RPC helps perform specific actions (or functions), while SOAP/REST is used to retrieve resources (or data).

REST refers to a REST architecture, which partially dictates how API calls are formatted. Put simply, REST allows a client to request resources from a server, which returns the information to the client in its current state. REST APIs often use the HTTP protocol to format requests and responses, but are also compatible with the (FTP), SMTP, and others. They can return data to API clients using several different formats, including XML, JavaScript object notation (JSON), and hypertext markup language (HTML).

Are APIs vulnerable to security risks?

Like anything connected to a network, APIs are vulnerable to exploitation and abuse. Common API attacks include the following:

• Authentication-based attacks: Authentication is a critical part of ensuring that API calls are sent and received from legitimate sources. However, attackers can still bypass these measures to carry out attacks, either by intercepting authentication tokens, stealing API keys, or using other tactics to obtain confidential credentials.
• Vulnerability exploits: API vulnerabilities — such as broken object level authorization, broken user authentication, excessive data exposure, and others from the OWASP API Security Top 10 — refer to flaws in an API that may allow attackers to access them without permission. By exploiting these flaws, attackers can carry out data breaches or use APIs to launch more complex attacks.
• DDoS attacks: Attackers may flood APIs with volumetric traffic in an attempt to interrupt (or completely halt) the service it provides.

Cloudflare API Gateway helps mitigate these attacks by providing strong authentication, scanning payloads for sensitive data, validating API schemas, and detecting and preventing API abuse. Learn more about Cloudflare API Gateway.