APIs and Contracts

In modern software systems, applications rarely interact with backend logic directly. Instead, they communicate through APIs, which act as controlled entry points into the system.

A client — such as a browser, mobile application, or another backend service — sends a request to a specific API endpoint. The API receives that request, interprets the information it contains, and forwards it to the appropriate backend logic. The backend then performs the necessary work, such as retrieving data from a database or executing application rules, before returning a response back to the client.

This structured communication allows systems to remain modular. Frontend applications, mobile apps, and external services can interact with the same backend functionality as long as they follow the API's defined request and response format.

Because APIs define how requests must be structured and what responses will look like, they create a predictable interface between different parts of a system. This interface allows independently developed components to communicate reliably without needing to know how the internal backend implementation works.

When a client sends a request to an API endpoint, it must specify what type of operation it wants to perform. This operation is expressed using an HTTP method.

The HTTP method works together with the endpoint URL to define the meaning of the request.

For example, a request like GET /users asks the server to retrieve user data. A request like POST /users asks the server to create a new user. A request such as DELETE /users/42 instructs the backend to remove a specific user.

Several HTTP methods are commonly used in APIs.

GET retrieves existing data from the server.
POST creates new resources.
PUT replaces an existing resource with new data.
PATCH updates part of an existing resource.
DELETE removes a resource from the system.

By combining endpoints with HTTP methods, APIs clearly define the operations that clients are allowed to perform on system resources.

In API design, one approach is to structure endpoints around actions, where each URL describes what the system should do. For example, an endpoint like POST /createUser directly encodes the action into the URL.

This approach works for small systems but becomes difficult to maintain as the number of features grows. Endpoints become inconsistent, and it becomes harder to predict how new functionality will be exposed.

REST takes a different approach by organizing APIs around resources such as users, orders, or products. Instead of encoding actions in the URL, the endpoint represents the resource, and the HTTP method defines the operation.

For example, POST /users creates a new user, while GET /users retrieves users. This separation leads to a consistent pattern across the entire API.

Because of this structure, RESTful APIs are easier to understand, scale, and extend. Developers can interact with new endpoints more easily since they follow the same predictable design.

REST is built on a set of design principles that help APIs remain consistent and reliable as systems grow.

One key principle is stateless communication. Each request must contain all the information needed for the server to process it. The server does not rely on previous requests, which makes the system easier to scale and distribute.

Another principle is resource-based design. APIs represent entities such as users or orders as resources, and these resources are identified using URLs like /users or /orders.

REST also relies on standard HTTP semantics. HTTP methods such as GET, POST, PUT, PATCH, and DELETE are used to clearly express the operation being performed on a resource.

Finally, REST enforces a uniform interface. Endpoints follow consistent patterns, making APIs easier to understand and reducing confusion when interacting with different parts of a system.

When a server processes a request, it must communicate the result back to the client. HTTP status codes provide a standardized way to describe that outcome.

Status codes are grouped into categories. Codes in the 2xx range indicate success, meaning the request was processed correctly. Codes in the 4xx range indicate client errors, such as invalid input or missing resources. Codes in the 5xx range indicate server errors, meaning something went wrong on the backend.

Common examples include 200 OK, which indicates a successful request, and 201 Created, which confirms that a new resource was created. Errors such as 400 Bad Request indicate invalid input, while 401 Unauthorized signals missing or invalid authentication. A 404 Not Found response means the requested resource does not exist, and 500 Internal Server Error indicates a failure on the server.

Clients use these status codes to determine how to proceed. For example, a client may retry a request after a server error or prompt a user to correct input after a client error.

In distributed systems, requests can fail, time out, or be retried multiple times. Because of this, backend systems must be designed to handle repeated requests safely.

An operation is considered idempotent if sending the same request multiple times results in the same final state. For example, calling DELETE /users/10 once removes the user. Calling it again does not change anything further because the user is already deleted.

Similarly, PUT /users/10 replaces the resource with the same data each time, so repeating the request does not create additional side effects.

In contrast, POST /orders is typically not idempotent because each request creates a new order. Repeating the same request can result in duplicate resources.

Idempotency is important because systems often retry requests automatically when failures occur. Without idempotency, retries could lead to inconsistent data, duplicated operations, or unintended side effects.

As backend systems evolve, APIs often need to change. New features may be added, data formats may be updated, or existing behavior may be modified.

The problem is that clients such as web apps, mobile apps, or third-party integrations rely on existing API behavior. If the API changes without warning, those clients can break.

API versioning solves this by allowing multiple versions of an API to exist at the same time. Older clients can continue using the original version, while newer clients can adopt updated versions.

One common approach is URL versioning, where the version is included in the path, such as /v1/users and /v2/users. Another approach is header versioning, where the client specifies the version using a header like Accept: application/vnd.api.v2.

By versioning APIs, backend systems can evolve safely while maintaining compatibility with existing clients.

An API contract acts as an agreement between the client and the backend system. It defines exactly how communication should happen so both sides can interact without ambiguity.

When a client sends an HTTP request, it must follow the contract by using the correct endpoint, providing the expected data format, and including all required information. The backend system processes the request based on these rules and returns a structured HTTP response.

The contract defines several critical aspects of the API, including the available endpoints, the format of request data, the structure of responses, the meaning of status codes, and the expected behavior of each operation.

Because of this contract, clients do not need to understand how the backend is implemented internally. As long as they follow the defined interface, communication remains consistent and reliable.

In practice, API contracts are essential for collaboration between frontend and backend teams, as well as for integrations between independent systems.