APIs allow websites, mobile apps, internal systems, and third-party services to exchange data and request actions in a predictable way. This Cn2data glossary explains the terminology most often encountered when designing, building, securing, testing, and operating an API.
The definitions are intended for beginners, but they also identify practices that matter in production systems. Some terms describe universal technical concepts; others describe widely used conventions whose exact implementation can vary by API.
A
Access token
A credential a client presents when calling a protected API. Access tokens are normally short-lived and limited to particular permissions. They must be protected from disclosure and transmitted over HTTPS.
Actor
The person, application, service, or worker responsible for an operation. Recording the actor helps an API produce a useful audit history.
Adapter
Code that connects an application's internal logic to an outside interface or service. Examples include HTTP, database, storage, payment, email, and malware-scanning adapters.
API
An application programming interface: a defined way for software systems to communicate. An API specifies what requests clients may make, what data they must supply, and what responses they can expect.
API client
The application or service that sends requests to an API. A web frontend, mobile app, partner platform, command-line program, or another backend service can all be API clients.
API contract
The documented agreement between an API and its clients. It defines endpoints, methods, request and response formats, authentication rules, error behavior, and other expectations.
API endpoint
A particular HTTP method and URL that performs an API operation. For example, GET /api/v1/orders/123 might return order 123.
API gateway
A service positioned in front of one or more APIs. It may route requests, terminate TLS, authenticate clients, enforce rate limits, collect metrics, or apply security policies.
API key
A value used to identify or authenticate a calling application. API keys are simpler than many token systems but often provide less precise identity and permission control. They should be treated as secrets.
API versioning
A strategy for changing an API without unexpectedly breaking existing clients. A version may appear in the URL, such as /api/v1/, or in a header or media type.
Assertion
A statement one system makes to another, often signed so the recipient can verify its origin and integrity. A signed JWT is one common form of assertion.
Asynchronous processing
Work performed separately from the original request. Long-running tasks such as video conversion, report generation, or file scanning are often placed in a queue and handled by background workers.
Audience
The intended recipient of a token, commonly represented by the JWT aud claim. Checking the audience prevents a token issued for one service from being accepted by another.
Audit event
An append-only record of an important action, decision, or state change. Audit events help answer who did what, when, and to which resource.
Authentication
The process of verifying the identity of a user, application, or service. Passwords, API keys, signed tokens, certificates, and OAuth flows are common authentication mechanisms.
Authorization
The process of deciding what an authenticated identity may do. Authentication answers “Who are you?”; authorization answers “What are you allowed to access or change?”
B
Background worker
A process that performs queued work outside the immediate HTTP request-response cycle. Workers allow an API to respond promptly while slower work continues reliably.
Bearer token
A token sent in the HTTP Authorization header using Bearer TOKEN. Possession is normally enough to use it, so it must be protected and sent only over HTTPS.
Bulk operation
An operation that reads, creates, updates, or deletes multiple resources at once. Bulk endpoints can improve efficiency but require careful validation, authorization, error reporting, and transaction design.
C
Cache
Temporary storage that allows a previous result to be reused. Correct caching can improve speed and reduce server load, but sensitive or rapidly changing responses may require directives such as Cache-Control: no-store.
Claim
A named fact carried in a token. JWT claims may describe the issuer, audience, subject, expiration time, token ID, tenant, or permissions.
Client credentials
Credentials used by an application to authenticate as itself rather than as a human user. OAuth 2.0 client credentials are commonly used for service-to-service APIs.
Clock skew
A small difference between the clocks of separate computer systems. Token validators often allow a brief tolerance when checking issued-at, not-before, and expiration times.
Concurrency
Multiple operations occurring during overlapping periods. APIs must account for concurrent requests so they do not create duplicates, overwrite newer data, or produce invalid states.
Content type
The format of an HTTP request or response body, identified by the Content-Type header. Common examples are application/json, multipart/form-data, and text/plain.
CORS
Cross-Origin Resource Sharing: browser-enforced rules controlling whether a webpage from one origin may call an API at another origin. CORS is not a substitute for authentication or authorization.
Correlation ID
An identifier propagated across related requests, services, jobs, and logs. It helps operators trace one business operation through a distributed system.
CRUD
Create, Read, Update, and Delete: the four basic categories of data operations. Not every API should expose all four for every resource.
curl
A command-line program for sending HTTP requests. Developers commonly use it to test endpoints and inspect response headers and bodies.
D
Database migration
A version-controlled change to a database schema or required seed data. Migrations allow environments to apply structural changes consistently.
Database transaction
A group of database operations that succeed or fail as one unit. Transactions help prevent partially completed business operations.
Dependency
An external package, library, framework, or service an application relies on. Dependencies should be versioned, monitored, and updated deliberately.
Deprecation
The process of marking an API feature as scheduled for removal or replacement. A good deprecation policy provides notice, migration instructions, and a realistic transition period.
Dispatcher
A process that selects pending work or messages and sends them to the appropriate worker or external destination. Reliable dispatchers generally support leasing, retries, and failure tracking.
Django
A Python web framework that provides URL routing, HTTP handling, database models, migrations, forms, security features, and testing tools. It is one of many frameworks that can be used to build APIs.
Domain model
The application's representation of business concepts and rules. Examples include customers, orders, policies, payments, files, and their permitted state changes.
Domain service
Application code that performs a business operation while enforcing domain rules. Keeping these rules in a service layer can prevent different API endpoints or workers from implementing them inconsistently.
E
Endpoint
See API endpoint.
Environment variable
A configuration value supplied outside application source code. Environment variables commonly provide deployment-specific settings, although dedicated secret-management systems are preferable for sensitive credentials.
Error code
A stable, machine-readable identifier describing an API error, such as INVALID_REQUEST or PAYMENT_DECLINED. It is more dependable for client logic than a human-readable message.
Eventual consistency
A model in which separate parts of a system may temporarily show different states but converge after asynchronous processing completes. APIs should make this behavior clear to clients.
Expected state
The state a caller believes a resource is in before requesting a change. Comparing it with the stored state helps detect stale or conflicting operations.
H
Header
A named piece of metadata attached to an HTTP request or response. Headers carry information such as authorization, content type, caching rules, request IDs, and accepted response formats.
HTTP
Hypertext Transfer Protocol, the request-response protocol most web APIs use. An HTTP request normally contains a method, URL, headers, and sometimes a body.
HTTP method
A verb describing the requested action. Common methods are GET, POST, PUT, PATCH, and DELETE.
HTTP status code
A three-digit number summarizing the result of an HTTP request. Examples include 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, and 500 Internal Server Error.
HTTPS
HTTP protected by TLS. HTTPS encrypts data in transit and helps clients verify that they are communicating with the intended server.
I
Idempotency
The property that repeating the same logical request has the same intended effect as making it once. Idempotency is especially important when clients retry requests after a timeout.
Idempotency key
A client-generated identifier attached to a retryable request. The server stores the key and result so accidental redelivery does not create a duplicate operation.
Immutable
Not permitted to change after creation. Immutable events, policies, and evidence can improve auditability because later operations cannot silently rewrite history.
Ingress
The infrastructure entry point through which external traffic reaches an application. It may handle TLS, routing, filtering, or load balancing before forwarding a request to the API.
Issuer
The authority that created and signed a token, commonly represented by the JWT iss claim. The receiving API must verify that the issuer is trusted.
J
JSON
JavaScript Object Notation, a widely used text format for structured API data. A JSON object contains named values, while a JSON array contains an ordered list of values.
JSON Web Token
A compact token format, usually called JWT, that carries claims and can be signed or encrypted. A JWT is a format, not a complete security design; the API must still validate its signature, algorithm, issuer, audience, timestamps, and required claims.
K
Key ID
A label, often represented by kid in a JWT header, that identifies which cryptographic key should be used to verify a signature.
Key rotation
Replacing a cryptographic key while maintaining service availability. Systems commonly allow old and new verification keys to overlap until tokens signed with the old key have expired.
L
Lease
A temporary claim that a worker is processing a queued item. If the worker fails to finish before the lease expires, another worker can retry the work.
Least privilege
The practice of granting only the permissions required for a task. Clients, users, services, and workers should not receive broader access than they need.
Load balancer
A component that distributes incoming requests across multiple API servers. It improves capacity and availability and may also terminate TLS or perform health checks.
M
Message broker
Infrastructure that transports messages between services and workers. Brokers support asynchronous processing but require decisions about delivery guarantees, retries, ordering, and duplicate handling.
Middleware
Code that runs before or after an endpoint handler. Middleware commonly performs authentication, request logging, CORS handling, request-ID generation, or response-header enforcement.
Multi-tenant
An architecture in which one application serves multiple customer organizations while isolating their data and permissions. Tenant identity must come from trusted authentication context rather than unverified request data.
O
OAuth 2.0
An authorization framework that lets clients obtain limited access tokens. Different OAuth flows support user-delegated access, service-to-service access, and devices with limited input capabilities.
Object storage
A storage system that manages files as objects rather than ordinary filesystem paths. Cloud object storage commonly supports metadata, access policies, versioning, and time-limited upload or download URLs.
OpenAPI
A machine-readable specification for describing HTTP APIs. An OpenAPI document can support interactive documentation, client generation, validation, testing, and collaboration.
Operation ID
A stable identifier for one logical command or business operation. It can support replay protection, auditing, and correlation across retries.
ORM
Object-relational mapper: software that lets application code work with relational database records as language-level objects. Django includes an ORM.
Outbox pattern
A reliability pattern in which an application writes both a business change and an outgoing message to the same database transaction. A dispatcher sends the message after the transaction commits.
P
Pagination
Dividing a large result set into smaller pages. Common designs use page numbers, offsets, or opaque cursors. Responses should explain how to request the next page.
Parameter
A value supplied to an endpoint. Parameters may appear in the URL path, query string, headers, or request body.
Path parameter
A value embedded in the URL path, such as the 123 in /orders/123. It usually identifies a particular resource.
Payload
The meaningful data carried by a request, response, token, event, or queued message. In HTTP, the term often refers to the body.
PEM
A text encoding commonly used for cryptographic keys and certificates. PEM data contains Base64-encoded material between markers such as —--BEGIN PUBLIC KEY—--.
Permission scope
A named permission that limits what a token or client may do. Examples might include orders:read and orders:write.
PostgreSQL
An open-source relational database frequently used by production APIs. It supports transactions, constraints, indexing, row locking, JSON fields, and sophisticated concurrency controls.
Private key
The secret half of an asymmetric cryptographic key pair. It may be used to create digital signatures or decrypt data and must not be shared with the verifying service.
Public key
The shareable half of an asymmetric key pair. A recipient can use it to verify signatures created with the corresponding private key.
Q
Query parameter
A value included after ? in a URL, such as status=open in /orders?status=open. Query parameters commonly control filtering, sorting, searching, or pagination.
Queue
A holding area for work that will be processed asynchronously. Queues help absorb traffic spikes and allow failed work to be retried.
R
Race condition
A defect in which an outcome depends unexpectedly on the timing of concurrent operations. Transactions, locks, version checks, uniqueness constraints, and idempotency controls help prevent race conditions.
Rate limiting
Restricting how many requests a client may make during a period. Rate limits protect capacity, reduce abuse, and promote fair use.
Request body
Data sent with an HTTP request. JSON is common, but APIs may also accept form fields, files, text, or binary data.
Request ID
A unique identifier assigned to one HTTP request. Returning it to the client and recording it in logs makes troubleshooting easier.
Resource
An entity or collection exposed by an API, such as a customer, invoice, file, or order. REST-style URLs often use nouns to identify resources.
Response body
Data returned by an endpoint. Its format is described by the response Content-Type header and the API contract.
REST
Representational State Transfer, an architectural style often used for HTTP APIs. REST-style designs generally model resources, use standard HTTP methods and status codes, and keep requests self-contained.
Retry
A repeated attempt after a temporary failure or uncertain result. Safe retries require idempotency, appropriate delays, and a limit on the number of attempts.
Retry with backoff
A retry strategy that waits progressively longer between attempts. Adding random jitter helps prevent many clients from retrying simultaneously.
Row lock
A database lock that temporarily prevents conflicting changes to the same record. Row locks can protect critical transitions but should be held for as little time as possible.
RSA
An asymmetric cryptographic system using a private key and public key. It is commonly used for digital signatures, including some JWT algorithms.
RS256
A JWT signing algorithm that uses RSA with SHA-256. Secure implementations explicitly allow the intended algorithm instead of trusting an unverified token to select it.
S
Schema
A formal description of data structure, including field names, types, formats, and constraints. Schemas can validate requests and responses and improve generated documentation.
SDK
A software development kit that wraps an API in convenient functions or objects for a particular programming language or platform.
Secret
Sensitive information used to authenticate or authorize access, such as a password, API key, private key, or client secret. Secrets should not be committed to source control or written to ordinary logs.
Serialization
Converting application data into a transport format such as JSON. Deserialization converts received data back into application-level values and must include validation.
Service account
A nonhuman identity used by an application, automated process, or worker. It should have narrowly defined permissions and managed credentials.
Scope
See Permission scope.
State transition
A controlled change from one defined resource state to another. Explicit transitions help enforce rules such as which actions are allowed before approval, payment, completion, or deletion.
Status endpoint
An endpoint that reports the current state or progress of an operation, especially one performed asynchronously.
T
Tenant
A customer organization or isolated account in a shared application. Multi-tenant APIs must enforce tenant boundaries on every relevant operation.
Test database
A database reserved for automated tests. It prevents tests from changing development or production data and can be recreated whenever the suite runs.
Throttling
Slowing or rejecting requests to protect an API or enforce usage limits. The term is often used interchangeably with rate limiting.
TLS
Transport Layer Security, the encryption and authentication protocol used by HTTPS. It protects API requests and responses while they travel across networks.
Token expiration
The time after which a token must no longer be accepted. Short lifetimes reduce the damage possible if a token is stolen.
Transaction boundary
The precise set of database operations that succeed or fail together. Network calls generally should not occur while a database transaction or row lock is held.
Trust boundary
The point at which data or control passes between components with different levels of trust. Input crossing a trust boundary must be authenticated, authorized, validated, and handled according to its risk.
U
Uniqueness constraint
A database rule preventing duplicate values within a defined scope. It provides stronger concurrency protection than an application-only “check before insert.”
URL
A Uniform Resource Locator identifying an API resource or operation, such as https://api.example.com/v1/orders/123.
UUID
A universally unique identifier. UUIDs are often used for public resource IDs, request IDs, event IDs, or operation IDs when centralized sequential numbering is undesirable.
V
Validation
Checking that input has the required type, format, length, allowed values, and relationships before using it. Validation does not replace authentication or authorization.
Virtual environment
An isolated Python environment containing one project's interpreter context and dependencies. It helps prevent package versions for different projects from interfering with one another.
W
Webhook
An HTTP request one system sends to another when an event occurs. Reliable webhooks normally use signed payloads, stable event IDs, retries, timeouts, and duplicate handling.
Worker
A process that performs background jobs from a queue or another work source. Workers should verify that work is current, make repeated delivery safe, and report failures without silently losing the job.
Common JWT claims
aud
The audience claim. It identifies the service or services intended to accept the token.
exp
The expiration-time claim. It specifies when the token must stop being accepted.
iat
The issued-at claim. It records when the token was created.
iss
The issuer claim. It identifies the authority that created and signed the token.
jti
The JWT ID claim. It uniquely identifies the token.
nbf
The not-before claim. It specifies the earliest time at which the token may be accepted.
scope
A commonly used claim containing the permissions requested or granted. Its exact format is defined by the authorization system.
sub
The subject claim. It identifies the user or other principal represented by the token.
Common HTTP methods
DELETE
Requests removal of a resource. Depending on the API, deletion may be immediate, reversible, asynchronous, or implemented as a status change.
GET
Retrieves a resource or collection and should not intentionally change server state.
PATCH
Applies a partial update to a resource.
POST
Submits data for processing or creates a resource or operation. Repeated POST requests may create duplicates unless the API provides idempotency controls.
PUT
Creates or fully replaces a resource at a known URL. Correctly implemented PUT operations are idempotent.
Common HTTP status codes
200 OK
The request succeeded and the response contains the result.
201 Created
A new resource was created successfully. The response commonly identifies its URL.
202 Accepted
The request was accepted for asynchronous processing but has not necessarily finished.
204 No Content
The request succeeded and there is no response body.
400 Bad Request
The request is malformed or fails basic validation.
401 Unauthorized
Authentication is missing, invalid, or expired. Despite its name, this status is primarily about authentication.
403 Forbidden
The caller is authenticated but is not permitted to perform the requested action.
404 Not Found
The requested resource does not exist or is intentionally concealed from the caller.
409 Conflict
The request conflicts with the resource's current state or with another operation.
410 Gone
The resource existed previously but is no longer available.
415 Unsupported Media Type
The server does not support the request body's content type.
422 Unprocessable Content
The request is syntactically valid but contains semantic validation errors. Some APIs use 400 instead.
429 Too Many Requests
The client exceeded a rate limit and should wait before retrying.
500 Internal Server Error
The server encountered an unexpected failure. Public responses should avoid exposing stack traces, credentials, or internal diagnostics.
502 Bad Gateway
A gateway or proxy received an invalid response from an upstream service.
503 Service Unavailable
The service is temporarily unable to handle the request, often because of overload or maintenance.
504 Gateway Timeout
A gateway or proxy did not receive a timely response from an upstream service.
About this glossary
This glossary is a general educational resource from Cn2data. Individual APIs may use different terminology, authentication systems, status codes, and design conventions. Always consult the API's own documentation before integrating with it.