When you open a bookstore app and search for a book, the app needs information: the title, author, price, and whether the book is available. That information may live on a server somewhere else. The app needs a defined way to ask for it and understand the answer.

An API provides that interface. Understanding what an API exposes, what it hides, and what callers can expect is the starting point for designing one.

This chapter develops those ideas through a bookstore example and follows a request from an app to a service and back.

API stands for Application Programming Interface. It is a defined set of operations and rules that software can use to interact with another software component. An operation is something the component lets a caller do, such as retrieve a book or calculate a delivery cost.

The word interface describes the point of interaction. A person uses a bookstore's search box and buttons. The code behind that screen uses an API to request book information. The interface tells the caller what it can ask for, what information it must supply, and how to interpret the result.

Consider how those interactions connect:

The API returns information the app can use. The app decides how to present it, perhaps as a list on a phone or a grid on a website. This lets different user interfaces work with the same underlying operations.

APIs also support programs without a visible screen. An inventory process could use an API to update stock counts, and a scheduled report could use one to retrieve sales totals. A human does not need to click a button for an API call to happen.

An API does not require an internet connection. A library can expose functions that run inside the calling program. An operating system can expose operations for working with files. A browser can expose capabilities to the JavaScript running in a page. These are all programming interfaces.

A remote API lets a program interact with a component across a network. The bookstore app is an example: it sends a message to a catalog service, a program that provides catalog information.

For the rest of this example, assume that the bookstore exposes a remote API using HTTP, the Hypertext Transfer Protocol. A protocol defines rules for exchanging messages. HTTP defines requests and responses, including methods, status codes, and headers. The software making a request acts as the client, and the software handling it acts as the server.

Those names describe roles in an interaction. A mobile app can be a client, but so can another service. A server handling one request might make its own request to a different server.

HTTP is one way to communicate through an API. The broader idea is the same for both local and remote interfaces: the caller uses a defined operation without needing to know every step inside its implementation.

Suppose a reader opens the detail page for a book with the identifier book_1042. An identifier is a value that distinguishes a particular item. In this fictional bookstore, book details are public, so this read operation does not require a login.

The app requests the URL https://api.bookstore.example/books/book_1042. A URL gives the address of what the client wants to access. An endpoint is an address that an API exposes; when describing a particular HTTP operation, developers commonly specify both its method and its URL or path.

Here is an illustrative HTTP/1.1 request to that address over HTTPS, which protects HTTP traffic in transit:

GET asks to retrieve information. The path /books/book_1042 identifies the book, and Host identifies the server's host. Headers carry information about the message; here, Accept says that the client accepts JSON as a response format. This request does not need a body.

The server finds the book and responds:

200 OK is an HTTP status indicating that the request succeeded. Content-Type identifies the response body's format, and Content-Length gives its length in bytes. The example body is exactly the single line above, with no trailing newline. These message elements have defined HTTP meanings.

The body carries the book data. JSON is a text format for structured data; this object contains named fields such as title and inStock. The app reads those fields and displays a book detail page.

In this example's API, amountMinor represents the amount in the currency's minor unit. For USD, 2499 means 2,499 cents, or $24.99. The bookstore chooses this field name and meaning. HTTP does not define book identifiers, price fields, or stock information.

The exchange fits into a larger flow inside the service:

The app sends the request and receives the response. The storage lookup is an implementation step inside the service. The client does not need to know the database query or how the service stores the price.

An API's contract describes what a caller must provide and what behavior it can expect in return. “Contract” here means a technical agreement about interaction. It includes more than the address of an endpoint or the shape of a JSON object.

For the book lookup, the contract needs to answer several questions:

The answers determine how the client behaves. For example, this bookstore defines inStock: true to mean that at least one copy was available when the service checked. Reading that value does not reserve a copy. Another customer could buy the last one before this reader reaches checkout.

You cannot learn that distinction from the field's Boolean type alone. A type describes the kind of value, such as a string, number, or Boolean. The field's meaning describes what that value tells the caller about the business.

Failure behavior belongs to the contract too. This example could define a malformed book identifier as a 400 Bad Request and an unknown, correctly formed identifier as a 404 Not Found. An existing book with no stock still returns 200 OK, with inStock: false. Those are choices for this API, consistent with the HTTP status meanings; an empty shelf does not mean the catalog entry is missing.

A remote call may also fail before the client receives an HTTP response, for example if it cannot connect to the server. The client must distinguish that situation from a response saying that the book does not exist.

Documentation communicates the intended contract, and the running implementation must honor it. A field can be valid JSON and still violate the contract: returning 2499 as dollars when the documentation promises cents would give the client the wrong price.

The implementation is the code and internal machinery that carry out an operation. For the catalog service, that includes looking up records, calculating availability, and building responses.

The API exposes selected capabilities while hiding those internal steps. This is abstraction: callers work with the information they need for a task without depending on every detail of how it happens.

The bookstore might initially read directly from a database. As traffic grows, it could add a cache, a temporary store that helps the service answer some reads faster. The diagram shows two possible implementations behind the same interface:

These branches represent alternatives. The app can keep using the same operation if the new implementation preserves the contract, including any promises about how recently the information was checked. Keeping field names unchanged is not enough if the behavior changes in a way callers cannot handle.

This separation also explains why an API is more than a database access path. A catalog API may combine stored information with business rules, and other APIs may perform calculations or trigger work without retrieving a database record at all. The interface describes the capability the caller can use; the implementation determines how to provide it.

An API defines how software interacts with another component through supported operations, inputs, results, and behavior. APIs can be local or remote; HTTP requests and responses are one way to use a remote API.

The API contract gives callers a shared understanding of both successful and unsuccessful interactions. The implementation performs the work behind that contract. Keeping the contract separate from the implementation lets callers use the API without depending on how it works internally.