Introduction
Define API broadly as a programming interface, distinguish local programming interfaces from external HTTP APIs, and introduce API paradigms as alternative ways to design services.
An API (Application Programming Interface) is a defined set of rules, contracts, and protocols that allows different software applications and components to communicate with each other.
At its core, an API acts as an intermediary or messenger: it accepts a request from one program, conveys it to another system or service, and delivers the resulting response back to the caller.
What is an API Contract?
An API contract is a formal agreement defining the expected inputs, outputs, and error formats between a client and server to ensure predictable communication.
How an API Works
Regardless of whether an API connects two local functions in memory or two microservices across continents, communication follows a structured 3-stage lifecycle:
- The Request: An application sends a structured message requesting data or triggering an action (e.g., querying current weather conditions, retrieving user profiles, or authenticating credentials).
- The Intermediary & Contract: The API receives the request and validates it against predefined interface rules and schemas to ensure the caller has supplied valid parameters and permissions.
- The Response: The target system executes the requested operation, generates the output, and returns the response back through the API to the calling application.
Two Broad Kinds of APIs
An API is a way for software parts to communicate. APIs can work locally or over a network.
| Kind | Where it works | Examples |
|---|---|---|
| Local API | On the same machine or inside the same program | Math.max, fs.readFile, OS system calls |
| Network API | Between different machines or services | REST, GraphQL, gRPC, Stripe API |
Remember
An external HTTP API is one specific manifestation of an API. A local function signature, an OS system call, and a remote web endpoint are all APIs operating in different contexts.
Understanding API Paradigms
An API paradigm is the way an API is designed and how clients communicate with it.
┌─────────────────────────────────────────────────────────────────────────────────┐
│ API Concept │
├───────────────────────────────────────┬─────────────────────────────────────────┤
│ Concept Layer │ What it Represents │
├───────────────────────────────────────┼─────────────────────────────────────────┤
│ 1. The API │ The programming interface and contract. │
│ 2. Context (Local vs External) │ Where the interface runs and connects. │
│ 3. API Paradigm │ The design style used to structure it. │
└───────────────────────────────────────┴─────────────────────────────────────────┘Common network API paradigms include:
- REST: Works with resources and uses HTTP methods like GET, POST, PUT, and DELETE.
- GraphQL: The client asks for exactly the data it needs.
- RPC / gRPC: The client calls a remote function or procedure.
- Event-Driven / Streaming: The server pushes data in real time using WebSockets, SSE, or message brokers.
Core Idea
Key Takeaways
- An API is an interface that lets software communicate.
- APIs can be local or network-based.
- An API paradigm describes how the API is designed.