What is an API endpoint?

What is an API endpoint?

An application programming interface (API) is a way for an application to request a service from another application. APIs enable developers to avoid rebuilding application features that already exist. An API endpoint is the place where those requests (known as API calls) are fulfilled.

If Alice and Bob are talking to each other on the phone, Alice's words travel to Bob and vice versa. Alice directs her words at the "endpoint" of the conversation: Bob.

Alice: "Hello, Bob" ----------> Bob

Similarly, an API integration is like a conversation. But instead of saying "Hello," an API client says something like "I need some data" to the API server — making an API call. The API server endpoint then says "Here is the data" — an API response. And API endpoints are not physical entities like Alice and Bob; they exist in software, not hardware.

API servers and API clients

APIs are hosted on one or more servers — specialized computers that store data and execute software programs. Each server "serves" data, content, and software functionality to other devices over the Internet. The API endpoint is almost always hosted on a server.

The other end of the API connection is the API client — the entity requesting services from the API. Some call this the API "user," even though most API calls are automated.

How does an API client know the server's endpoint?

To be usable, an API has to have documentation. The documentation indicates, among other things, what types of requests the API will accept, what the API can do, how it formats its responses, and what its endpoints are. Developers can review an API's documentation and incorporate this information as they build their applications.

As an example, see Cloudflare's API documentation, including what the endpoints are, here: https://api.cloudflare.com/

How do APIs use URLs?

Uniform resource locators (URLs) are used for multiple purposes on the web, including locating webpages. For example, the URL for the American English version of this webpage is https://www.cloudflare.com/learning/security/api/what-is-api-endpoint/. When a user enters that URL into their browser, the browser knows where to find this webpage and can load it.

URLs also indicate API endpoints. When Alice and Bob talk on the phone, Alice calls Bob at Bob's phone number. Similarly, an API endpoint URL is like a phone number for making API calls.

An API server can host one or multiple API endpoints, meaning it will accept and process calls directed at those endpoints' URLs. API clients also need to have a URL so that the API server knows where to send its replies, just as Bob and Alice both need a phone number for phone calls between them to work. Developers set this URL when building their applications.

A URL always includes the application layer protocol, such as HTTP, used to reach it. Most web APIs use HTTP, so that is included in the API endpoint's URL.

How do API endpoints and clients authenticate?

A properly designed API does not accept API calls from just anybody. This would leave the API server open to receiving malicious data from attackers. In addition, API usage often costs money, so in those cases the API server has to check if the API call comes from a paying customer.

For these reasons, the API server has to make sure that the API client where the call comes from is known and trusted. It does this via authentication.

Authentication is the process of verifying identity. Just as there are several ways for a human user to authenticate to a system, there are four main ways that API endpoints can enforce authentication:

1. API key: The API client is assigned a key, or a unique string of characters that only they and the API service know. When the API client sends an API call to the server endpoint, it includes the key so that the server knows where the call came from.
2. Basic authentication (username and password): Similar to the key approach, the API client sets up a username and password with the API service, and it includes these credentials in API calls.
3. OAuth token: Instead of requiring authentication from the client, an API server can get an authentication token from a trusted authentication server using the OAuth protocol.
4. Mutual TLS: TLS is the protocol that creates an authenticated connection between client and server when loading webpages. It can also authenticate both sides of an API integration.

In many cases, mutual TLS is the most effective authentication method. For one thing, it authenticates both endpoint and client, not just the client, so both sides can be sure they are receiving data from a legitimate source. It also uses private keys, which are never shared between endpoints and therefore cannot be intercepted in transit. On the other hand, API keys, passwords, and tokens can all be duplicated or stolen.

Cloudflare API Shield uses mutual TLS to authenticate API endpoints and clients, helping protect both sides from an attack. API Shield also offers several other API security features, including rate limiting and data loss prevention (DLP) — learn more about API Shield.