In this Glossary, you can find important terminology related to API documentation, implementation, authentication, authorization, and related concepts
A-E
A |
B |
C |
D |
E |
|---|
A
Accept Header
An HTTP request header that tells the server which content types (e.g., application/json, application/xml) the client is able to process in the response.
API (Application Programming Interface)
A set of rules and protocols that allow different software applications to communicate with each other.
API Documentation
Technical documentation that describes how to use an API, including endpoints, request/response formats, authentication methods, and usage examples.
API Gateway
A management tool that sits in front of an API, managing requests, security, and traffic.
API Key
A unique identifier used to authenticate a client application.
API Security
Measures taken to protect an API from unauthorized access, attacks, and data breaches.
API Testing
Software testing that involves directly testing APIs, and as part of integration testing to determine if the API meets expectations regarding functionality, reliability, performance and security of the application.
Authentication
The process of verifying the identity of a user or application.
Authorization
The process of granting or denying access to specific resources or actions based on the authenticated identity.
B
Bearer Token
An access token used in OAuth 2.0 authorization.
Body (HTTP)
The data payload of an HTTP request or response.
C
Caching
Storing frequently accessed data in a temporary storage location to improve performance.
Client ID/Secret
A pair of credentials provided to a client application when it registers with an authorization server (used in OAuth 2.0) to identify the application.
CORS (Cross-Origin Resource Sharing)
A security mechanism that allows a web page's scripts to interact with resources from a different domain (origin) than the one the script originated from.
cURL
A command-line tool for transferring data with URLs.
D
Developer Portal
A centralized website that serves as a single source of truth for all information developers need to understand, integrate with, and build applications using an organization's APIs and services.
Docs as code
A philosophy and set of tools that applies software development workflows (like version control, automated testing, and review processes) to the creation and maintenance of documentation.
E
Endpoint
A specific URL that represents a resource or action exposed by an API.
F-J
F |
G |
H |
I |
J |
|---|
F
Framework (Documentation)
A foundational structure, often comprised of static site generators, templates, and build tools, used to automate the process of turning source documentation files (like Markdown) into the final, published website. It is the core tool used to implement the Docs as Code approach.
G
GraphQL
A query language for APIs and a runtime for fulfilling those queries with existing data. It provides a more efficient and flexible alternative to REST.
H
Header (HTTP)
A key-value pair that provides additional information about an HTTP request or response.
HTTP (Hypertext Transfer Protocol)
The underlying protocol used by the World Wide Web and APIs for communication between clients and servers. Common methods include GET, POST, PUT, DELETE, and PATCH.
HTTP (Hypertext Transfer Protocol) defines a set of request methods (often called "verbs") to indicate the desired action to be performed on a specific resource (e.g., by an API client). Each method implements a different semantic, specifying what action the client is requesting from the server.
HTTP Method
The table below lists the most common HTTP methods used in API design and communication.
| HTTP Method | Description |
|---|---|
| GET | Retrieves a representation of the specified resource. It is the most common method and is intended to be safe (no side effects) and idempotent (multiple identical requests have the same effect as one). |
| HEAD | Asks for a response identical to a GET request, but without the response body. This is useful for checking metadata (like headers) before downloading a large resource. |
| POST | Used to submit an entity to the specified resource, often causing a change in state or the creation of a new resource (e.g., submitting a form or uploading a file). |
| PUT | Replaces all current representations of the target resource with the request payload. It is idempotent (uploading the same file twice overwrites the original). |
| DELETE | Deletes the specified resource. |
| PATCH | Applies partial modifications to a resource. This is different from PUT, which replaces the entire resource. |
| OPTIONS | Used to describe the communication options (e.g., which methods are allowed) for the target resource. |
HTTPS (Hypertext Transfer Protocol Secure)
The secure version of HTTP, which uses SSL/TLS for encryption.
I
IdP (Identity Provider)
A system that creates, maintains, and manages identity information, and provides authentication services to relying applications (like your API).
J
JSON (JavaScript Object Notation)
A lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate.
JSON Schema
A specification for describing the structure, content, and format of JSON data. It is used to validate that API request and response bodies adhere to a defined structure.
JWT (JSON Web Token)
A compact, URL-safe means of representing claims to be transferred between two parties.
K-O
K |
L |
M |
N |
O |
|---|
K
Key (or API Key)
A simple, unique identifier used to authenticate a client application. It is typically passed in a request header or query parameter to track usage and enforce limits.
L
Latency
The delay (measured in time) between a client sending an API request and receiving the first byte of the API response. Low latency is crucial for a fast user experience.
M
Markdown
A lightweight markup language with plain text formatting syntax. It is the preferred format for writing documentation in a Docs as Code workflow due to its readability and ease of conversion to HTML.
Microservice
An architectural approach where a single application is composed of many smaller, independent services, each running in its own process and communicating via lightweight mechanisms, often RESTful APIs.
Mocking
Creating simulated objects or services to test the functionality of an API without relying on actual external dependencies.
N
Nonce (Number Used Once)
A unique, often random, number issued in an authentication request to prevent the request from being captured and re-used by an attacker (Replay Attack).
O
OAuth 2.0
OAuth2 is an authorization protocol that enables apps to access information on behalf of users without requiring users to expose their username and password. With OAuth2, security credentials are exchanged for an access token. For example:
mary:marys_password (username:password), or
Md3npJPSDBJrKmmVvDHkdbBAxN4u9eCA:doQIWfMAitAa85CoHPt (key:secret)
becomes an access token, for example:
a0btAbaKLGHp3CFm7xs4DDxLmaeN.
The access token is a random string of characters that is usable for a limited time. Ideally, it expires after a short time (e.g., 300 seconds), making this authentication method in an app workflow more secure than using actual credentials.
To learn more about OAuth2, visit their official website.
OpenAPI Specification (OAS)
A specification for describing RESTful APIs, enabling both humans and computers to discover and understand the capabilities of a service without access to source code, additional documentation, or network traffic inspection.
P-T
P |
Q |
R |
S |
T |
|---|
P
Payload
The data transmitted in a request or response.
Polling
A client repeatedly making requests to an API endpoint to see if a new data update or status change is available. This is less efficient than using a Webhook.
Postman
A collaboration platform for API development, used for building, testing, and documenting APIs.
Q
Quality Assurance (QA)
The systematic process of reviewing, testing, and verifying that documentation meets established standards for accuracy, clarity, completeness, technical correctness, and usability.
Query Parameter
Optional key-value pairs appended to the end of a URL (after a ?) used to filter, paginate, or specify how a resource should be returned from an API Endpoint.
R
Resource
Any information component that can be named, accessed, or manipulated by an API, such as a user, a product, or a collection of objects. This is the core concept of a RESTful API.
Rate Limiting
A mechanism for controlling the number of requests a client can make to an API within a given time period.
Request
A message sent from a client to an API server, typically including a method, URL, headers, and body.
Response
A message sent from an API server to a client, typically including a status code, headers, and body.
REST (Representational State Transfer)
An architectural style for designing networked applications, emphasizing stateless communication and resource-based interactions.
S
Schema
A formal description of the structure, content, and organization of data, used to validate and describe the expected format of request and response bodies (e.g., in JSON or XML).
SDK (Software Development Kit)
A collection of software development tools in one installable package.
SOAP (Simple Object Access Protocol)
A protocol for exchanging structured information in the implementation of web services, using XML.
SSL/TLS (Secure Sockets Layer/Transport Layer Security)
Cryptographic protocols that provide communication security over a computer network.
Status Code
A three-digit integer that indicates the result of a request. Common examples include 200 (OK), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), and 500 (Internal Server Error).
Swagger
The previous name of OpenAPI Specification (OAS). A set of open-source tools built around the OpenAPI Specification that can help you design, build, document, and consume RESTful Web services.
T
Throttling
A backend process that dynamically limits the number of requests an API consumer can make over a specific period. It is similar to Rate Limiting but is often implemented to protect the API infrastructure from being overloaded.
U-Z
U |
V |
W |
X |
Y |
Z |
|---|
U
URI (Uniform Resource Identifier)
A string of characters that identifies a name or a resource on the internet. A URL (Uniform Resource Locator) is a type of URI that also provides the means of locating the resource.
V
Versioning (API)
The practice of releasing multiple versions of an API to accommodate changes without breaking existing clients.
Versioning (API documentation)
The practice of maintaining and publishing documentation that corresponds precisely to a specific version of the API, ensuring developers use the correct instructions.
W
Webhook
An automated message sent from apps when something happens. They deliver data to other applications as it happens, meaning you get data immediately, unlike typical APIs where you would need to poll for data very frequently.
X
XML (Extensible Markup Language)
A markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable.
Y
YAML (YAML Ain't Markup Language)
A human-friendly data serialization standard often used for configuration files and data-exchange between languages. It is commonly used for defining OpenAPI Specifications and CI/CD pipelines.
Z
Zero Trust
A security model based on the principle of "never trust, always verify." It requires all users, even those inside the organization's network, to be authenticated, authorized, and continuously validated before being granted access to resources (like APIs).