What is an API? Definition, examples and how it works

An API (application programming interface) is a defined way for one piece of software to ask another for data or to perform an action. It lists the operations you can call, the inputs each one accepts and the output each one returns. How the work gets done stays hidden behind it.

The term covers two common cases. A web API is a service that answers requests sent over the network, usually over HTTP. A library API is the set of functions and types that a code package exposes to the program that imports it.

Both work the same way from the caller's side. You send a request in the agreed form and get a result in the agreed form, without reading the code on the other side.

A weather service is a typical web API. Your app sends an HTTP GET request to a URL called an endpoint, such as /v1/weather on the provider's server, with the city as a query parameter. The server replies with a status code and a JSON body.

A library API follows the same idea inside one program. JavaScript's JSON.parse takes a string and returns the value it describes, or throws a SyntaxError if the text isn't valid JSON. You never see how the parser works, only what it accepts, returns and throws.

Browsers offer APIs too. The fetch function is a browser API that your code calls to send HTTP requests, often to a web API.

Web APIs come in a few styles. REST APIs expose resources at URLs and act on them with HTTP methods such as GET and POST. GraphQL APIs accept queries at a single endpoint and return only the fields asked for. gRPC sends Protocol Buffers messages over HTTP/2 and is common between internal services.

The rules both sides agree on are the API's contract. A caller that follows the contract can expect the documented result. A provider that keeps it can change everything behind it without breaking anyone.

Providers publish the contract as reference documentation, and many also publish a machine-readable description such as an OpenAPI document. Tools can generate client code, tests and documentation from that file.

For a web API, the contract usually covers:

Once other people's code depends on an API, the provider no longer controls every caller. Renaming a response field, turning a number into a string or making an optional parameter required can break apps the provider has never seen.

Versioning gives providers a way to make such changes without breaking existing callers. A new version, such as /v2/ in the path, carries the incompatible change while /v1/ keeps working for a published period. Additive changes, like a new optional field, usually need no new version.

As a caller, read the changelog and deprecation notices for the APIs you depend on, and pin the version you tested against.

Most web APIs require each request to carry a credential. Simple services issue an API key, a long random string that identifies your application. APIs that act on a user's data usually use OAuth 2.0, where the user approves access and your app receives a short-lived access token. Either way, the credential travels in a header such as Authorization, over HTTPS, and it belongs on a server or in protected storage, never in public code.