Glossary · Definition
API
An API (Application Programming Interface) is a contract that lets one program request something from another — typically over HTTP, in JSON. 'Web APIs', 'REST APIs', 'GraphQL APIs' are all flavors of the same idea: a defined surface for programmatic access.
Definition
An API (Application Programming Interface) is a contract that lets one program request something from another — typically over HTTP, in JSON. 'Web APIs', 'REST APIs', 'GraphQL APIs' are all flavors of the same idea: a defined surface for programmatic access.
What it means
An API documents what requests are valid (URLs, methods, parameters, body shape) and what responses to expect (status codes, body shape, headers). The dominant style on the web is REST: each resource has a URL, HTTP verbs (GET, POST, PUT, PATCH, DELETE) act on it, JSON bodies carry the data. GraphQL replaces many endpoints with one — clients ask for exactly the fields they need in a typed query language, the server resolves it. RPC (gRPC, JSON-RPC) treats API calls as remote function invocations rather than resource manipulation. Underneath all three: a request goes out, a response comes back, both sides agreed on the shape ahead of time.
Advertisement
Why it matters
Every modern integration runs through an API. A good API is consistent (same patterns everywhere), self-describing (OpenAPI / GraphQL schema documents it), versioned (so changes don't break clients), authenticated (API keys, OAuth, mTLS), rate-limited (so one client can't break it for the rest), and idempotent where it matters (so retries don't double-charge customers). Bad APIs leak implementation, change without notice, return inconsistent error shapes, and force every client to write the same workarounds.
Frequently asked questions
REST vs GraphQL?
REST is simpler, better-cached, and works with any HTTP tool. GraphQL is more efficient when clients need different subsets of related data. Either is fine; the wrong one is whichever one isn't documented.
What's an API key?
A long random string the client sends (in a header or query parameter) to identify itself. Cheaper than full OAuth for server-to-server use; not appropriate for client-side apps where users shouldn't see the key.
What's an API rate limit?
A cap on requests per time window per client (per IP, per API key, per user). Common caps: 60-1000 requests/minute. APIs return HTTP 429 (Too Many Requests) when you hit it; respect the Retry-After header.
Related terms
- DefinitionOAuthOAuth is the open-standard protocol that lets a user grant a third-party app limited, scoped access to their account at another service — without sharing their password. 'Sign in with Google', GitHub OAuth apps, Slack-to-Notion integrations all run on OAuth 2.0.
- DefinitionJWTA JWT (JSON Web Token, pronounced 'jot') is a compact JSON token signed by an issuer. Three base64url-encoded parts joined with dots: header.payload.signature. Used for stateless auth, OIDC ID tokens, and signed messages between services.
- DefinitionHTTPSHTTPS is HTTP wrapped in a TLS-encrypted tunnel. Everything between your browser and the server — URLs, form data, cookies, response bodies — is encrypted in transit so a network observer (cafe Wi-Fi, ISP, anyone in between) can't read it or change it.