Understanding Web APIs: What They Are and How They Work

Teresa Torres introduces a multi-week series arguing that API teams need more product discovery, and aims to bridge API engineers and discovery practitioners. This installment explains the basics: what an API is, how HTTP requests and responses work, and how REST APIs use endpoints, methods, and schemas. It also covers authentication, including when a developer uses their own credentials versus acting for an end user. The piece matters because usability problems in APIs stem from these foundations, and understanding them is needed to evaluate API product decisions.

01Key takeaways

• APIs let code talk to other code, and most modern products depend on integrations built this way.
• HTTP methods such as GET, POST, PUT, PATCH, and DELETE tell the server how to act on a resource.
• Status codes like 200 OK, 404 Not Found, and 500 Internal Server Error communicate the outcome of each request.
• Endpoints map to resources, and API documentation must clearly define each resource's required fields and data types.
• Developers must decide whether to authenticate with their own credentials or with end-user credentials, often via OAuth.

02Key sections

Why API teams need discovery

The author frames the series' goal: connect API teams unfamiliar with discovery and discovery practitioners unfamiliar with APIs. She previews the upcoming articles on usability challenges and real-world stories.

What an API is

An API is a predefined instruction set that lets code communicate with other services. Examples like Google Calendar and Stripe show how most modern products rely on integrations powered by APIs.

How HTTP requests and responses work

Requests contain a method, endpoint, headers, and optional body, while responses carry a status line, headers, and body. Headers act like envelopes carrying metadata, and status codes signal success or failure.

REST APIs and endpoints

REST builds on HTTP so code can send and receive data. Well-designed endpoints map to resources, and each supports a subset of HTTP methods that define which actions are available.

Resource schemas and authentication

Documentation must describe each resource's fields and types so developers can create or update them correctly. Credentials in headers determine access, and OAuth lets developers act on behalf of end users.

03From the post

“A common question we get is, “Do API teams need to do discovery?” My short answer is yes. But I realize to effect change in the industry, I need a longer answer. Over the next several weeks, I’m going to do my best to provide a more complete answer.”

04Frameworks mentioned

Summary and takeaways written by PM Atlas; quotes are short excerpts. © the original author.