A Web Application Programming Interface is a set of rules and protocols that allow software applications, such as clients and servers, to communicate with each other over the internet or private networks.

Their primary purpose is to expose specific functionalities that allow external applications to programmatically request and interact with resources hosted on a server.

The communication typically happens through standard communication protocols like HTTP, and the data is often exchanged in formats like JSON.

Web APIs promote modularity and interoperability by enabling software applications to evolve independently and use different technologies as long as the API contract remains stable.

The API contract

To communicate, the consumer and the provider (typically the client and the server) must both adhere to a set of rules called an API contract.

This contract dictates how the API can be used, what requests can be made, and what responses are expected.

It defines the exact structure, format, and behavior of the API, ensuring consistency and predictability in interactions.

The API contract usually includes:

• Endpoints: the specific URLs that the API exposes for different functionalities.
• HTTP methods: the allowed operations that can be performed on the resources (e.g., GET, POST).
• Request parameters: the inputs the client must provide when sending a request (e.g., query parameters, message bodies).
• Response structure: the format and structure of the data returned by the API (e.g., JSON).
• Status codes: the HTTP status codes that indicate the result of a request (e.g., 200 OK, 404 Not Found).
• Authentication and authorization: the mechanisms required to verify the identity of the client (e.g., API key, OAuth token).
• Rate limits and quotas: the restrictions on how frequently the API can be accessed within a given time period (e.g., 100 requests per hour).

Example