API Glossary
Every API term you need to know, clearly defined. From REST and GraphQL to webhooks and OAuth, this glossary covers30+ essential API concepts with plain-language explanations.
API Terms and Definitions
API
Application Programming Interface
A set of rules and protocols that allows software applications to communicate with each other. APIs define the methods and data formats that programs use to request and exchange information. When you use a weather app, it calls a weather API to fetch forecast data.
Learn more:Api DesignREST
Representational State Transfer
An architectural style for building web APIs that uses standard HTTP methods (GET, POST, PUT, DELETE) to operate on resources identified by URLs. REST APIs are stateless, cacheable, and return data in formats like JSON. Over 80% of public APIs use REST.
SOAP
Simple Object Access Protocol
A protocol for exchanging structured information using XML. SOAP includes built-in security (WS-Security), transaction support, and formal contracts (WSDL). It is more complex than REST but remains important in enterprise banking, healthcare, and government systems.
Learn more:Rest Vs SoapGraphQL
A query language for APIs developed by Facebook. Unlike REST, where the server determines the response structure, GraphQL lets clients request exactly the data they need. This eliminates over-fetching and under-fetching. A single GraphQL endpoint replaces multiple REST endpoints.
gRPC
Google Remote Procedure Call
A high-performance framework for connecting services using Protocol Buffers for serialization. gRPC supports streaming, bidirectional communication, and strong typing. It is primarily used for microservice-to-microservice communication where speed matters more than simplicity.
OpenAPI
OpenAPI Specification (formerly Swagger Specification)
An industry-standard format for describing REST APIs. An OpenAPI document defines your endpoints, request/response schemas, authentication methods, and more in YAML or JSON. Tools like Specway use OpenAPI specs to generate interactive documentation automatically.
Swagger
The original name for the OpenAPI Specification (pre-2016) and a suite of open-source tools for working with OpenAPI specs. Swagger UI renders interactive API documentation. Swagger Editor lets you edit specs visually. The spec itself was renamed to OpenAPI when donated to the Linux Foundation.
Learn more:Api DocumentationEndpoint
A specific URL path in an API that performs a particular operation. For example, GET /api/users is an endpoint that returns a list of users, and POST /api/users is an endpoint that creates a new user. Each endpoint combines a URL path with an HTTP method.
Learn more:Api DesignHTTP Methods
The verbs used in HTTP requests to indicate the desired action. GET retrieves data, POST creates new resources, PUT replaces an existing resource, PATCH partially updates a resource, and DELETE removes a resource. REST APIs use these methods to provide predictable behavior.
Learn more:Api DesignRequest / Response
The two halves of an API interaction. A request is sent by the client and includes an HTTP method, URL, headers, and optional body. A response is returned by the server and includes a status code, headers, and optional body containing the requested data or error information.
API Key
A unique string used to authenticate API requests. API keys identify the calling application and are typically passed in a header (Authorization: Bearer sk_live_...) or query parameter. API keys are simpler than OAuth but less secure for user-delegated access.
Learn more:Api DesignOAuth 2.0
Open Authorization 2.0
An authorization framework that lets third-party applications access resources on behalf of a user without exposing their password. OAuth uses access tokens with specific scopes. When an app asks to "Sign in with Google," that is OAuth in action.
JWT
JSON Web Token
A compact, self-contained token format used for authentication and information exchange. A JWT contains three Base64-encoded parts: header (algorithm), payload (claims like user ID and expiration), and signature. JWTs enable stateless authentication because the server does not need to store session data.
Rate Limiting
A technique that restricts the number of API requests a client can make within a time window (e.g., 1,000 requests per minute). Rate limiting protects APIs from abuse and ensures fair usage. APIs communicate limits via headers like X-RateLimit-Remaining and return 429 Too Many Requests when exceeded.
Learn more:Api DesignWebhook
A mechanism where an API sends data to your server when an event occurs, instead of you polling for changes. For example, Stripe sends a webhook to your server when a payment succeeds. Webhooks are the "push" complement to the "pull" model of regular API calls.
SDK
Software Development Kit
A pre-built library that wraps API calls in language-native functions. Instead of writing raw HTTP requests, developers use SDK methods like stripe.customers.create(). SDKs handle authentication, serialization, error handling, and retries. They can be auto-generated from OpenAPI specs.
Learn more:Api DocumentationPagination
A technique for splitting large API responses into smaller pages. Offset-based pagination uses page and limit parameters. Cursor-based pagination uses an opaque cursor pointing to the next set of results. Cursor-based is more reliable for real-time data because it handles insertions and deletions correctly.
Learn more:Api DesignCORS
Cross-Origin Resource Sharing
A browser security mechanism that controls which websites can call your API. By default, browsers block requests to different domains. CORS headers (Access-Control-Allow-Origin) tell the browser which origins are allowed. Misconfigured CORS is one of the most common API integration problems.
Idempotency
A property where making the same API request multiple times produces the same result as making it once. GET, PUT, and DELETE are naturally idempotent. POST is not. APIs use idempotency keys (unique request IDs) to make POST requests safe to retry, preventing duplicate charges or records.
Learn more:Api DesignAPI Versioning
The practice of maintaining multiple versions of an API simultaneously. URL-based versioning (/api/v1/users, /api/v2/users) is the most common approach. Versioning lets you introduce breaking changes without disrupting existing integrations.
Learn more:Api DesignMiddleware
Software that sits between the client request and the API handler, processing requests before they reach your business logic. Common middleware handles authentication, logging, rate limiting, CORS, and request validation. Middleware runs in a chain, passing requests from one to the next.
API Gateway
A server that acts as the single entry point for all API requests. The gateway handles authentication, rate limiting, request routing, load balancing, and analytics. Popular gateways include Kong, AWS API Gateway, and Apigee. Think of it as a reverse proxy designed specifically for APIs.
Mock Server
A simulated API server that returns pre-defined responses based on an OpenAPI spec. Mock servers let frontend developers build against an API before the backend is ready. They are also useful for testing error scenarios, rate limits, and edge cases without hitting production.
Schema
A formal description of the structure and constraints of data. JSON Schema defines what fields an object should have, their types, which are required, and validation rules. OpenAPI uses JSON Schema to describe request bodies, response bodies, and parameters.
Learn more:Json To Json SchemaPayload
The data carried in an API request or response body. A JSON payload might contain user information, search results, or error details. Payload size affects performance, so APIs should return only the data the client needs and support pagination for large datasets.
Headers
Key-value metadata pairs sent with HTTP requests and responses. Common request headers include Authorization (credentials), Content-Type (data format), and Accept (desired response format). Common response headers include X-RateLimit-Remaining and Cache-Control.
Status Codes
HTTP Status Codes
Three-digit numbers indicating the result of an API request. 200 means success, 201 means created, 400 means bad request, 401 means unauthorized, 403 means forbidden, 404 means not found, 429 means rate limited, and 500 means internal server error. Good APIs use status codes consistently.
Learn more:Api DesignWSDL
Web Services Description Language
An XML-based format for describing SOAP web services. A WSDL document defines the operations, messages, data types, and network bindings of a SOAP API. WSDL is the SOAP equivalent of OpenAPI for REST APIs.
Learn more:Rest Vs SoapcURL
Client URL
A command-line tool for making HTTP requests. cURL is the universal language of API examples because it works on every operating system and clearly shows the HTTP method, headers, and body. Most API documentation includes cURL examples.
Learn more:Api DocumentationDeveloper Portal
A website where developers find everything they need to integrate with an API: documentation, API keys, SDKs, changelogs, rate limit information, and support. Specway helps teams build beautiful developer portals from their OpenAPI specifications.
Learn more:Api Documentation
Ready to Build Your API?
Import your OpenAPI spec and publish beautiful, interactive API documentation in minutes with Specway.