API Glossary for Developers

API terminology shifts meaning between providers, between books, and between decades. "REST", "API key", and "rate limit" all mean subtly different things depending on who's writing the docs. This glossary defines 35+ terms the way a working developer should think about them — what they do, what to watch for, and where they bite.

Terms are grouped by what they're for, not alphabetized. Authentication first because that's the first wall every API integration hits.

Authentication and access

API key: A long random string an API provider gives you at signup. You include it in every request, usually as a header or query parameter, and the provider uses it to identify your account and apply your rate limit and billing. Treat API keys as secrets: never commit them to git, never put them in client-side JavaScript that ships to the browser, never paste them in screenshots. Rotate them when they leak.
OAuth 1.0 vs OAuth 2.0: Two different authorization protocols often confused. OAuth 1.0 (deprecated by most APIs) signs each request cryptographically. OAuth 2.0 is what almost every modern API means by "OAuth" — the client gets a short-lived bearer token in exchange for a longer-lived refresh token, and the token goes in the Authorization header. OAuth 2.0 is more flexible but also has more failure modes (expired tokens, scope mismatches, redirect URI bugs).
Bearer token: An opaque string that grants access when included in an HTTP request as Authorization: Bearer <token>. Bearer tokens are usually issued by OAuth flows. The defining property: whoever holds the token can use it — there is no additional verification, so token leakage is total compromise. Always use HTTPS; never log full tokens.
Basic auth: The simplest HTTP authentication: Authorization: Basic <base64(username:password)>. Still common for server-to-server APIs where TLS protects the wire. Avoid for user-facing APIs — credentials get cached aggressively by browsers and proxies.
JWT (JSON Web Token): A signed JSON object that encodes claims (user ID, expiration, scopes). Common as a bearer token format because the API server can verify it without a database lookup. The signature only proves the token is unmodified; it does not prove the user is currently authorized — a stolen valid JWT works until it expires.
Authentication vs authorization: Authentication answers "who are you?" (you have a valid token). Authorization answers "what are you allowed to do?" (this token's scopes permit this action). A 401 response means authentication failed (you're not signed in). A 403 means authentication succeeded but authorization denied (you're signed in but can't access this resource). Most "permission denied" bugs are actually 403s confused with 401s.

Request structure

Endpoint: A specific URL path that performs one operation, like /v1/forecasts or /users/123/posts. "API endpoint" is sometimes used loosely to mean the base URL of the API; technically each path is its own endpoint.
Path parameter vs query parameter: Path parameters identify a resource: /users/123 — the 123 is part of the resource address. Query parameters modify a request: /users?role=admin&limit=10. The general rule: if changing the value changes what resource you're addressing, it's a path parameter. If it changes how the response is filtered, sorted, or paginated, it's a query parameter.
Request body / payload: The data sent in POST, PUT, or PATCH requests, typically JSON. Body content has size limits set by the API (usually 1-10 MB) and must match a documented schema. The Content-Type header must declare the format (application/json for JSON), otherwise many APIs default to misinterpreting the body as form data.
Content-Type: An HTTP header that tells the server what kind of data the request body contains. The most common values for APIs: application/json for JSON bodies and application/x-www-form-urlencoded for HTML form submissions. Sending the wrong Content-Type is the most common source of mysterious 400 responses from otherwise correct API integrations.
User-Agent: An HTTP header identifying the client software. For free public APIs (notably Nominatim and MET Norway) a missing or generic User-Agent will get your requests blocked. Set a recognizable string with contact info: MyApp/1.0 (you@example.com). Don't impersonate browsers like Chrome — providers explicitly ban this pattern as spoofing.
CORS (Cross-Origin Resource Sharing): Browser security mechanism: a website at origin A cannot fetch data from origin B unless B explicitly opts in via Access-Control-Allow-Origin response headers. CORS failures are browser-only — server-side calls (Node, Python, curl) don't enforce CORS. If your client-side fetch fails but the same request works in curl, it's almost certainly a CORS issue, not an API bug.

Response and status

HTTP status codes (overview): Three-digit numbers grouped by hundreds: 1xx informational (rare), 2xx success, 3xx redirect, 4xx client error (your fault), 5xx server error (their fault). Pay attention to the specific code, not just the family. 401 vs 403 vs 429 all mean very different problems even though they're all 4xx.
4xx vs 5xx errors: 4xx means the request was wrong: bad auth, malformed body, unknown endpoint, rate limit hit. Fixing 4xx means changing your request. 5xx means the server failed: outage, bug, overload. Fixing 5xx means waiting and retrying, possibly with exponential backoff. Retrying 4xx errors with the same request will fail identically every time.
429 Too Many Requests: The rate-limit response. The provider should include a Retry-After header indicating seconds to wait. Some providers also expose X-RateLimit-Remaining and X-RateLimit-Reset on every response so you can preemptively slow down. Repeatedly hitting 429 and retrying immediately will compound the problem — back off exponentially.
Pagination (offset vs cursor): Two strategies for navigating large result sets. Offset pagination uses ?page=2&per_page=50 — simple but breaks when the underlying data changes between requests (items shift between pages). Cursor pagination returns a next_page_token with each response that you pass back; stable across data changes but you can only go forward. Most modern APIs (Stripe, GitHub v4, Twitter v2) use cursors.
Idempotency: A property of an API operation where repeating the same request has the same effect as a single request. GET is idempotent by definition. POST usually isn't (POSTing a payment twice charges twice). Modern APIs add idempotency keys: a unique value you generate per logical operation; the API stores it and returns the cached response on retries. Without idempotency keys, retries on network failures are dangerous for state-changing operations.
JSON vs XML response: JSON has won the format war for most public APIs (smaller, easier to parse in JavaScript, more readable). XML survives in legacy enterprise APIs and SOAP services. A few weather APIs (notably 7Timer!) still default to XML — check the docs for a JSON alternative parameter.

Architecture and protocols

REST API: An architectural style based on stateless HTTP operations against named resources. The defining principles: resources have URLs, HTTP verbs (GET, POST, PUT, DELETE) map to operations, responses are self-describing. "REST" is widely misused — most APIs labeled REST are actually HTTP-RPC (using only POST against named endpoints). Don't get hung up on whether an API is "properly" REST; ask whether the design is consistent and predictable.
GraphQL: An API query language where the client describes the exact data shape it needs and the server returns precisely that. Eliminates the over-fetching and under-fetching problems of REST. Cost: complex caching, expensive queries can DoS the server (use depth limits and query allow-lists), and the tooling has a steeper learning curve. GitHub's v4 API is the most-cited public GraphQL example.
gRPC: A binary RPC protocol over HTTP/2 using Protocol Buffers as the serialization format. Faster than JSON over HTTP for high-throughput service-to-service calls but rarely exposed as a public API because it's hard to call from a browser. If your free public API supports gRPC, that's unusual and suggests an enterprise origin.
Webhook: The inverse of an API call: instead of you polling the provider for changes, the provider POSTs to your URL when something happens. The trade-off: you give up control of when calls happen, but you get real-time notifications without polling load. Webhooks require a public URL, idempotency handling (providers retry on failure), and signature verification (the provider signs each payload so you can prove it came from them).
API gateway: A reverse proxy that sits in front of one or more backend APIs to handle cross-cutting concerns: authentication, rate limiting, logging, routing, request/response transformation. Examples include Cloudflare Workers, AWS API Gateway, Kong, and Tyk. When a public API has consistent rate-limit behavior across very different-looking endpoints, that's usually a gateway in front.
SDK (Software Development Kit): A library in a specific language (Python, JavaScript, Go, etc.) that wraps the underlying HTTP API. SDKs handle auth refresh, retries, pagination, and serialization so your application code is simpler. Pros: less boilerplate. Cons: SDKs lag behind the underlying API, hide bugs, and increase your dependency footprint. For prototyping, use the SDK. For production at scale, often worth dropping to raw HTTP calls.

Reliability and operations

Uptime / SLA (Service Level Agreement): Uptime is the percentage of time an API responds correctly to requests over a window. SLA is a contractual commitment about uptime, usually attached to a paid plan ("99.95% monthly uptime with credits on failure"). Free tiers rarely come with SLAs — the provider can have outages without owing you anything. The 30-day uptime numbers on FreeAPI.watch are measured, not promised.
Latency / response time: The time between sending a request and receiving the response. Components: network propagation, TLS handshake, request queueing on the server, actual processing, response transfer. P50 latency is the median; P95 and P99 are the percentile values where most outliers live. A free API with great P50 but terrible P99 will feel fine in development and broken in production where the tail latencies aggregate.
Throttling: Deliberate slowdown applied when you exceed rate limits or unfair usage thresholds, instead of outright rejection. The provider returns success but takes longer. Less violent than a 429 but harder to detect. If your application's response times degrade gradually without obvious errors, you might be throttled rather than failing.
Backoff strategy (exponential): Wait progressively longer between retries. The classic pattern: 1 second, 2 seconds, 4 seconds, 8 seconds, with jitter (random variation) to avoid thundering-herd retry storms. Most production HTTP clients (axios, requests, urllib3) support this directly. Without exponential backoff, a temporary upstream failure becomes a self-inflicted DDoS.
Circuit breaker: A pattern where after N consecutive failures, your client stops trying for a cooldown period rather than continuing to hammer a broken upstream. Saves cost (no wasted calls), improves your latency (immediate fail vs timeout wait), and lets the upstream recover. Most service-mesh and resilience libraries (Polly, Resilience4j, Hystrix's successors) implement circuit breakers out of the box.
Health check: A simple endpoint (often /health or /ping) that returns a quick success response if the service is operational. Used by load balancers, monitoring systems, and orchestrators to decide whether to route traffic to an instance. FreeAPI.watch's hourly checks hit each API's documented health endpoint (or the lightest functional endpoint when no dedicated health URL exists).
Status page: A separate public site (usually a subdomain like status.example.com) where the provider posts current and historical incidents. Most are powered by Statuspage.io, Atlassian Statuspage, or Better Stack. They tend to under-report — providers prefer admitting outages later when they can't deny them, so a green status page doesn't mean everything is working.

Commercial and tier

Free tier: A plan that lets you use the API at no cost up to some usage threshold (calls per day, calls per month, etc.). The defining property: no payment information required to start. Distinct from "free trial" — see below.
Freemium: A model where a baseline level of service is permanently free and additional features or volume are paid. Most public APIs we monitor are freemium. Common patterns: free tier limited by request volume (OpenWeatherMap), feature set (CoinGecko Demo plan), or update frequency (commercial weather APIs).
Free trial vs free plan: A free trial requires payment information at signup, converts to paid automatically after N days, and charges if you forget to cancel. A free plan does not require payment information and stays free indefinitely (within usage limits). When a provider markets "Try free for 30 days," that's a trial. When they market "Sign up free," that's usually a free plan. Read the signup flow carefully.
Pay-as-you-go: Pricing model where you're billed per unit of usage (per API call, per gigabyte, per minute of compute) rather than a flat monthly fee. Pros: pay nothing when not using it; scales smoothly. Cons: cost estimation is hard; a bug or DDoS can produce a giant bill. Always set spending alerts.
Quota: The maximum amount of a resource you can consume in a given period — usually requests per minute, hour, day, or month. Quotas may apply per API key, per IP, per account, or in some combination. Provider definitions of "quota" sometimes conflate three concepts: hard limits (you'll be cut off), soft limits (you'll be billed extra), and rate limits (you'll be throttled if you spike).
Overage: Usage above your plan's quota, often billed at a premium per-unit rate. Some providers cap overages at a percentage of your plan to prevent runaway bills; others don't. Always check the overage policy before deploying — finding out it's "$0.01 per request above 100,000/month" after you've done 5 million is a bad day.

Why we wrote this

Many of the categories that trip up developers integrating free public APIs come from terminology that everyone assumes is shared knowledge but isn't. The Twitter API v1.1 shutdown caught teams unprepared partly because they didn't distinguish between authentication and authorization, between rate limits and quotas, or between a free tier and a free trial.

For a live look at how the APIs we monitor handle these concepts, browse our directory. For longer essays on free API economics and reliability, see our blog.