API

What Is an API?

Software built by different teams in different languages still has to exchange data, and an API is the contract that makes that exchange predictable. The team providing a service publishes what it accepts and what it returns. Everyone else writes code against that promise and never sees the database or business logic behind it.

The most familiar example is a checkout page. When an online store charges a card, its code does not talk to the card networks directly. It sends a request to a payment provider's API with the amount and a card token, and gets back a response saying whether the charge succeeded.

APIs are not limited to the web. A browser exposes APIs that JavaScript uses to change a page, and every programming language ships a standard library whose functions form an API. In day-to-day product work, though, "API" usually means a web API: an interface reached over the network, most often through HTTP.

Why Do APIs Matter for Software Products?

APIs decide how quickly a product can be assembled from existing services and how easily other products can build on it in turn.

• Most products are assembled from existing services. Payments, maps, email delivery, and user authentication are usually bought as API-based services instead of developed in-house. A team that can integrate well spends its engineering time on the features that set the product apart.

• APIs have become products in their own right. In Postman's 2025 State of the API survey of more than 5,700 API practitioners, 65% said their organization generates revenue from its APIs. The sample leans toward Postman users, so it reflects API-heavy teams more than companies in general.

• AI agents act through APIs. A language model that books a meeting or files a ticket does it by calling an API. In the same Postman survey, only 24% of respondents said they actively design APIs with AI agents in mind, and 60% still design primarily for human developers.

How Does an API Work?

A web API works through a cycle of requests and responses: the calling application asks for something at a known address, and the providing system answers in an agreed format.

• Requests and responses. The client sends a request to an endpoint, which is a specific URL such as /v1/customers, along with a method like GET (read) or POST (create). The server replies with a status code and, usually, data in JSON format. A 200 code means success, while a 404 means the resource does not exist.

• A written contract. Well-run APIs describe every endpoint and response in a machine-readable file, most often using the OpenAPI Specification (formerly Swagger). Tools read that file to generate documentation and client code, so the description and the running service stay in step.

• Authentication and authorization. API keys identify which application is calling, while OAuth 2.0 tokens let an application act on behalf of a specific user. Authorization then checks what that caller may touch. Getting this second step wrong is common enough that broken object-level authorization tops the OWASP API Security Top 10 (2023 edition).

• An architectural style. REST, GraphQL, gRPC, and the older SOAP are the most common styles. REST organizes an API around resources and standard HTTP methods. GraphQL, open-sourced by Facebook in 2015, lets the client ask for exactly the fields it needs in a single query.

• Limits and versions. Providers cap how many requests a client can make in a time window and return a 429 "Too Many Requests" code when the cap is hit. When the contract has to change in a way that would break existing clients, providers release a new version and keep the old one running for a published period.

What Tools Do Teams Use to Build and Manage APIs?

Teams use API clients to design and test requests before release, then rely on gateways and documentation platforms once the API is live.

• API clients for design and testing. Postman, Insomnia, and Bruno let developers compose requests and run automated tests against an API. Bruno stores collections as plain files, which makes them easy to keep in Git alongside the code.

• API gateways. Kong Gateway, Apigee, and Amazon API Gateway sit in front of an API and handle authentication and rate limiting in one place, instead of each service implementing its own.

• Documentation platforms. Redocly, ReadMe, and Swagger UI turn an OpenAPI file into interactive reference pages where developers can read about an endpoint and try it from the browser.

What Are the Key Characteristics of a Well-Designed API?

A well-designed API is predictable for the people calling it and stable enough that they can build on it without constant rework.

• Abstraction. The API exposes what a system does and hides how. The provider can rewrite the database layer or switch programming languages, and callers notice nothing as long as the contract holds.

• Backward compatibility. Adding a field to a response is safe. Renaming or removing one breaks every client that relied on it, so mature providers treat the contract as a public commitment.

• Consistency. Endpoints follow the same naming patterns and error formats across the whole API. A developer who has learned one endpoint can guess how the next one behaves.

• Clear, current documentation. Every endpoint and error code is described, ideally with examples. An API without documentation can only be used by the people who wrote it.

• A deliberate security boundary. The API is the front door to a system's data. It checks identity and permissions on every request, since a client can call any endpoint directly and skip the product's user interface entirely.

What Are the Benefits of Working With APIs?

Working with APIs lets teams reuse capabilities instead of rebuilding them, and lets separate parts of a system change without breaking each other.

• Faster delivery through reuse. A startup can add card payments or text-message notifications in days by calling an existing service, instead of spending months building and certifying its own.

• Parallel development. Once frontend and backend teams agree on an API contract, both can build at the same time. The frontend works against a mock server generated from the specification until the backend is ready.

• Replaceable internals. Because callers depend only on the contract, the provider can refactor or migrate the system behind it. This is what makes a gradual move from a monolith to microservices possible.

• New channels from one backend. A web app, mobile apps, partner integrations, and internal tools can all run on the same API, so business logic lives in one place.

What Are the Challenges of Working With APIs?

The main challenges of working with APIs are dependence on someone else's roadmap and the ongoing cost of keeping a public contract stable and secure.

• Third-party dependency. Building on an external API means inheriting its outages and its deprecation schedule. Wrapping the provider behind an internal interface makes switching easier later, but it adds a layer of code the team has to write and maintain.

• Versioning costs compound. Every old version kept alive for existing clients needs testing and security patches. Retiring versions quickly saves that effort but forces client teams to do migration work on the provider's timeline.

• A larger attack surface. Each public endpoint is another way into the system. Gateways and automated security testing reduce the risk, at the cost of added latency and another piece of infrastructure to run.

• Network calls are slower than local ones. A request that crosses the network takes milliseconds where an in-process function call takes nanoseconds. Batching and caching close much of the gap, but cached data can go stale and batched endpoints are harder to design.

What Is the Difference Between an API and an SDK?

An API is the contract a service exposes, while an SDK (software development kit) is a package of code and tools that makes it easier to use a platform, often by wrapping that platform's API.