What Is an API?

An API (Application Programming Interface) is a defined interface through which two programs talk to each other without knowing each other's internal details. It is a contract: it specifies what you can request and what comes back. The concept is broader than the web, a library or an operating system provides APIs too. Here, the focus is on web APIs, the interfaces between systems over a network.

Every app that shows the weather, triggers a payment, or loads a profile uses APIs in the background. Unlike a classic website, an API has no face: there is no button that forbids anything. What is allowed is decided solely by the logic behind it, and that is exactly where the most expensive gaps arise.

Two Communication Patterns

How systems talk over an API follows, at its core, one of two patterns:

• Request and response (request-response): the client asks, the server answers, one round trip per call. This is how REST, GraphQL, gRPC, and SOAP work.
• Event-driven: data flows as soon as something happens, without anyone actively asking. This is how WebSockets, webhooks, and message-based systems work.

How an API Is Described

So that people and tools can understand an API, it is described as a machine-readable specification: a list of all endpoints, parameters, and data formats. For REST APIs, OpenAPI (formerly Swagger) is the de facto standard. Depending on the API style, though, there are dedicated description languages: GraphQL comes with its own schema (SDL), gRPC uses Protocol Buffers (.proto), and for event-driven APIs there is AsyncAPI. Older alternatives are RAML and API Blueprint.

When the specification is created is also a deliberate decision. In the API-first (or design-first) approach, the contract is designed first, before a single line of code exists. That lets teams work against it in parallel, and documentation, mock servers, client code, and tests can be generated automatically from the specification, security questions can be clarified early too. The counter-approach is code-first, where the specification is generated afterward from the finished code.

Either way, the specification is contract and documentation at once, and it is the starting point where a security test begins: it exposes the entire attack surface.

Topics in Detail

Which API style is used depends on the use case. The following pages start with a comparison of the styles, then go deep into REST and HTTP (the most common case) as well as the other styles, and finally cover the cross-format topics.

The Styles at a Glance

REST and HTTP

Other Styles

Cross-Format

Frequently Asked Questions

Sources

• API (Glossary) MDN Web Docs
• Overview of HTTP MDN Web Docs
• What is OpenAPI? OpenAPI Initiative
• AsyncAPI AsyncAPI Initiative