What Is an API? Requests, Responses, and Software Contracts

Key takeaways

• An API is an application programming interface, and it need not use a network or JSON.
• A web API defines operations through requests, responses, and documented behavior.
• Valid request data does not establish permission to perform the requested action.
• Timeouts, retries, and compatibility are part of the interface contract.

An API, or application programming interface, is a defined interface through which software uses another component’s functionality.

A library exposing a function has an API. A browser exposing document operations has an API. A service accepting HTTP requests also has an API.

The MDN API glossary covers this broader meaning. Web APIs are one familiar example, so consider a shopping application placing an order.

The application does not need direct access to the seller’s database. It needs an agreed operation for requesting an order and understanding the result.

Read an API Request as an Operation

An illustrative HTTP request might look like this:

POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

{
  "productId": 42,
  "quantity": 2
}

The method is POST, the path is /orders, headers describe metadata and credentials, and the body contains the order data.

Together with the service address, the path identifies the endpoint being called. The example corresponds to https://api.example.com/orders.

These names are part of the contract. Sending count instead of quantity only works if the provider defines that alternative.

A Response Includes More Than Data

A successful synchronous creation could return:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.example.com/orders/874

{
  "id": 874,
  "status": "pending",
  "quantity": 2
}

The status code describes the HTTP outcome. The body describes the created order according to this example’s contract.

A pending order is not necessarily paid, packed, or shipped. The caller must understand the business status separately from the successful HTTP exchange.

HTTP status codes distinguish outcomes such as successful creation, missing resources, forbidden access, rate limiting, and server errors. Clients should handle documented outcomes rather than assume every response contains the success body.

JSON Is a Format, Not the Definition of an API

The example uses JSON because it is widely supported for structured data.

Other interfaces may use binary formats, XML, streams, function parameters, or other representations. HTTP APIs are not automatically REST APIs, and an API is not necessarily a remote service.

The common feature is a defined surface that another program can use without depending on all the internal implementation details.

That separation lets the order provider change storage or internal services while preserving compatible behavior for callers.

Validate the Request and Authorize the Action

The server needs to parse the body and check its structure. Is quantity an integer? Are required fields present? Is the product identifier in the accepted format?

Runtime validation addresses those questions.

The service must also establish whether the caller can place the order, whether the product exists, and whether inventory is available. Those are separate checks.

Authentication identifies or verifies the caller’s credentials. Authorization decides what that caller may do. Knowing an order ID should not grant access to another customer’s order.

Network Failure Can Leave the Outcome Unknown

Suppose the server creates the order, but the response is lost. The application sees a timeout.

That does not prove the order was rejected. Blindly sending another creation request can produce a second order.

An API can define an idempotency mechanism that associates retries with one intended operation, or a way to retrieve the outcome. The client must follow that documented behavior rather than invent a header and assume the server supports it.

Timeouts, retry limits, and user-visible uncertainty belong in the integration design.

An API Description Helps Callers Agree

A useful contract describes operations, credentials, required fields, response shapes, errors, limits, and relevant behavior.

OpenAPI provides a machine-readable description format for HTTP APIs. Tools can use it for documentation and other development tasks.

A description still needs to match the running service. Contract and integration tests examine different aspects of that agreement.

Before the backend exists, a mock API can help develop success and error flows, but its behavior is a model of the intended service.

Compatibility Includes Meaning

Renaming quantity breaks callers using the old field. Changing what “pending” means can also break them even when the response structure stays identical.

Providers need a migration strategy for incompatible changes. Clients need to follow documented pagination, rate limits, and evolving fields rather than relying on incidental behavior.

For the shopping application, the API’s value is the agreement: how to request an order, how to discover its outcome, and which failures to expect. That agreement makes separate software components usable together.

The useful promise of an API is what callers can rely on without knowing how the implementation works.