Glossary groups

These terms are all related to APIs in general.

API (Application Programming Interface)

A set of definitions, protocols, and tools for building software applications. APIs allow different systems to interact with each other programmatically. This course focuses mostly on REST APIs, but there are also language-based APIs such as Java, C++, Python, and more. I refer to these as native library APIs.

API contract

A documented agreement that specifies the behavior of the API, including endpoints, request methods, request payloads, response schemas, and more. See also OpenAPI specification document.

API documentation

Documentation that describes how an API works so that developers can understand and use it. Usually includes reference documentation, tutorials, code samples, and overviews.

API gateway

A server that acts as an intermediary for requests, often providing features like rate limiting, logging, security measures, and more. Many modern API gateways offer built-in support for importing Swagger (OpenAPI) definitions. This allows developers to quickly deploy, manage, and monitor their APIs using the Swagger definition as a starting point.”

API key

A unique identifier required to authenticate API requests. API keys control access to the API.

API portal

A developer-facing website that provides documentation, support, and access management for an API. Serves as the main interface for API consumers.

API reference

The documentation describing the endpoints, requests, parameters, responses, schemas, and other details about an API.

API versioning

A technique to make changes to your API without breaking the contract for existing users.

authentication

The process of verifying the identity of a user or client making an API request. Common authentication methods include API keys, OAuth, and basic auth.

authorization

The process of determining what permissions an authenticated user has for different operations and resources in the API.

curl

A command line tool for transferring data with URL syntax. curl is commonly used to demonstrate example API requests.

developer portal

A website that brings together documentation, code samples, SDKs, tools, and other resources to help developers use an API or set of APIs. The portal is a central location for developers to access everything they need.

endpoint

The specific address (URL) where an API can be accessed. It’s combined with the HTTP method to define the operations available. The endpoints indicate how you access the resource, while the method indicates the allowed interactions (such as GET, POST, or DELETE) with the resource. The same resource usually has a variety of related endpoints, each with different paths and methods but returning different information about the same resource. Similar to base url.

GraphQL

A query language and runtime for APIs, allowing clients to request only the data they need.

HATEOAS

Stands for Hypermedia as the Engine of Application State. Hypermedia is one of the characteristics of REST that is often overlooked or missing from REST APIs. In API responses, responses that span multiple pages should provide links for users to page to the other items.

native library API

API with code libraries for incorporating functionality directly into an application, rather than using network calls. Tied to a language and usually has a library file that you integrate into your project. Also called library API or class-based API.

parameters

Options that can be passed with an endpoint to influence the response, such as specifying the response format or number of results returned. Common types are header, path, and query string parameters.

paths

The available endpoints and operations in an API. Paths are the core resources that make up an API’s interface.

rate limiting

Policies that restrict the number of requests a user can make to prevent overload or abuse. Requests over the limit may be throttled or blocked.

request

A call made to an API, including the endpoint URL and parameters, headers, authorization, and other components needed to retrieve the desired information.

response

The data an API returns after receiving and processing a request. The response contains requested information or confirmation that an operation succeeded.

response body

The data returned by the server in response to a client’s request. It can contain information like resources (in case of a GET request) or status messages (like error messages). Usually in structured formats such as JSON or XML.

REST API

An API that follows REST (Representational State Transfer) principles by exposing resources through endpoints that can be interacted with using standard HTTP methods like GET, POST, PUT, and DELETE. REST APIs return data in easy-to-process formats like JSON.

resource

The core object or information managed by the API. Resources have different representations that can be retrieved or manipulated. A resource can be a single entity or a collection. For example, ‘users’ might represent a collection of users, while users/1’ represents a single user entity.

SDK (Software Development Kit)

A collection of tools and resources that allows developers to program applications for a specific platform, software, or service. SDKs include API client libraries, documentation, code samples, and guides. Note that an SDK can include various APIs, but an API does not include an SDK.

SOAP (Simple Object Access Protocol)

A messaging protocol for communication between web services, a predecessor to REST in many contexts.

specification

A detailed technical description of an API’s architecture, endpoints, parameters, sample requests/responses, and other implementation details. The most common API specification format is OpenAPI.

Swagger

A framework for the OpenAPI specification that includes a suite of tools for auto-generating documentation, client SDK generation, and more. In contrast to the term OpenAPI, Swagger now refers to API tooling related to the OpenAPI spec. Some of these tools include Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others. These tools are managed by Smartbear. Note: Although ‘Swagger’ was the original name of the OpenAPI spec, the name was later changed to OpenAPI to reinforce the open, non-proprietary nature of the standard. OpenAPI is still often referred to as Swagger.

URI (Uniform Resource Identifier)

A string of characters that identify a name or a resource. In RESTful APIs, URIs are used to identify resources.

These terms are all related to API methods.

CRUD

Create, Read, Update, Delete. These four programming operations are often compared to POST, GET, PUT, and DELETE with REST API operations.

DELETE

An HTTP method that removes a resource.

GET

An HTTP method that retrieves a resource. GET requests do not modify any resources.

HTTP method

The type of action indicated in an API request, such as GET, POST, PUT, DELETE. Determines if you are reading, creating, updating, or deleting a resource. Synonymous with HTT verb and similar to HTTP operation.

HTTP operation

Refers to a combination of an HTTP method and a specific URI or endpoint. For example, a GET request to /users might retrieve a list of users, while a POST request to the same endpoint might create a new user. So, the combination of GET with /users and POST with /users indicates two distinct operations. Thus, an operation provides a more comprehensive view, as it takes into account both the action (HTTP method/verb) and the target (URI or resource).

HTTP verb

Same as HTTP method. The term ‘verb’ is used because each method/verb indicates an action or behavior.

Idempotent methods

HTTP methods where multiple identical requests should have the same effect as a single request. For instance, GET, PUT, and DELETE are idempotent, but POST is not.

operation

The type of API call, such as GET, POST, PUT, DELETE. Indicates allowed interactions with a resource.

POST

An HTTP method that creates a new resource.

PUT

An HTTP method that updates an existing resource or creates a new resource if it doesn’t exist.

These terms are all related to API parameters.

Accept header

Part of the HTTP specification, it indicates the types of media that the client can process. For instance, specifying Accept: application/json will let the server know that the client expects JSON data.

authentication token

A token used to validate the identity of the client or user making the request. Synonymous with Authorization tokens or bearers.

authorization tokens or bearers

A type of header parameter, these are tokens used to identify and authenticate the user making the request. Commonly used with JWT (JSON Web Tokens) and OAuth.

base URL

The main part of the URL, which usually doesn’t change. Parameters are then added to this base URL to access different resources or perform specific operations. Similar to endpoint.

Bearer token

A type of access token that is passed in the header for API requests to authenticate the user. See authorization tokens or bearers.

caching headers

Headers like ETag, Last-Modified, Cache-Control, and Expires that help control how responses are cached by the client or intermediate proxies.

headers

Metadata sent with both API requests and responses. Headers can include information about the type of content being sent, authorization details, and more.

header parameters

Parameters that are included in the request header, usually related to authorization.

OAuth

An open-standard authorization protocol that allows third-party services to exchange your information without exposing your password.

parameters

Options that can be passed with an endpoint to influence the response, such as specifying the response format or number of results returned. Common types are header, path, and query string parameters.

path parameters

Parameters that appear within the path of the endpoint, before the query string (?). Path parameters are usually set off within curly braces {}.

query string parameters

The part of a URL after the ? symbol that contains parameter names and values to configure an endpoint request. Multiple parameters are separated with &.

rate limit headers

Headers that inform the client about how many requests they can make in a given timeframe and when they can make additional requests after reaching the limit.

request body

The data submitted in the body of the request, often used to create or update a resource. Defined in OpenAPI under requestBody. Synonymous with request payload.

request example

A sample API request showcasing how the endpoint should be accessed, including any required headers, parameters, or body content.

request payload

Same as request body.

response headers

Information, in key-value pairs, sent in the response from the server. They can provide metadata about the response data, indicate caching rules, or specify any cookies to be stored.

These terms are all related to API responses.

Content-Type header

Part of the HTTP specification, it’s used to indicate the type of data contained in the body of the message, whether it’s in an HTTP request or response. It allows the client or server to interpret how the data should be processed.

error message

A descriptive message accompanying error status codes to provide more context on the nature of the error.

payload

The data returned in the body of an API response. The payload contains the requested information or data from the API.

response body

The data returned by the server in response to a client’s request. It can contain information like resources (in case of a GET request) or status messages (like error messages). Usually in structured formats such as JSON or XML.

response code

HTTP status codes returned with API responses indicating success, failure, errors, etc.

response example

Shows a sample response from the request example. The response example is typically not comprehensive of all parameter configurations or operations, but it does correspond with the parameters passed in the request example.

response headers

Information, in key-value pairs, sent in the response from the server. They can provide metadata about the response data, indicate caching rules, or specify any cookies to be stored.

response schema

The description of the response from an API endpoint. The response schema documents the response in a more comprehensive, general way, listing each property that could possibly be returned, what each property contains, the data format of the values, the structure, optional/required aspects, and other details.

status code

A 3-digit number returned with an API response indicating whether the request succeeded or failed. Common status codes include 200 (success), 400 (bad request), 404 (not found), 500 (server error).

These terms are all related to documentation formats and tools.

API Blueprint

The API Blueprint spec is an alternative specification to OpenAPI or RAML. API Blueprint is written in a Markdown-flavored syntax. See API Blueprint in this course, or go to API Blueprint’s homepage to learn more.

Asciidoc

A lightweight text format that provides more semantic features than Markdown. Used in some static site generators, such as Asciidoctor or Nanoc.

continuous delivery

Synonymous for continuous integration/continuous deployment (CI/CD).

continuous integration/continuous deployment (CI/CD)

Automation practices where changes to code are automatically tested and deployed. Useful for constantly updating documentation sites.

DITA

Darwin Information Typing Architecture, an XML-based architecture for authoring, producing, and delivering technical information. Allows topic-based authoring.

docs-as-code

Treating documentation files like code by using lightweight markup, version control, plain text editors, and engineering tools/workflows. Facilitates developer contributions.

documentation pipeline

The automated process that transforms raw source content, often in Markdown or other formats, into a live documentation site.

documentation theme

A predefined set of styles, layouts, and behaviors applied to documentation generated by static site generators or documentation tools.

frontmatter

Metadata at the beginning of a Markdown or other lightweight markup language file. Typically written in YAML and defines site-specific attributes.

HAT

Help Authoring Tool. Refers to the traditional help authoring tools (RoboHelp, Flare, Author-it, etc.) used by technical writers for documentation. Tooling for API docs tends to use docs-as-code tools more than HATs.

Hugo

A static site generator that uses the Go programming language as its base. Along with Jekyll, Hugo is among the top 5 most popular static site generators. Extremely fast site generation time.

i18n

Short for internationalization. There are 18 letters between i and n in the word internationalization. See localization/internationalization.

Java

General purpose programming language commonly used in enterprise application development. Preferred by some organizations over languages like PHP.

Javadoc

A documentation generator that produces API reference documentation from Java source code comments formatted with tags. The Javadoc tool is the standard for documenting Java APIs.

JSON

JavaScript Object Notation. A common data format for API responses, consisting of attribute-value pairs and arrays. OpenAPI (Swagger) specifications are often written in JSON. YAML tends to be more human-readable, while JSON is often easier for machines to process.

l10n

Short for localization. There are 10 letters between the l and n in localization. See Localization/Internationalization.

Localization/Internationalization (l10n/i18n)

The process of adapting documentation to different languages and regions.

Markdown

A lightweight markup language that uses plain text formatting syntax that gets converted to HTML. Popular format with developers writing documentation.

markup language

A system for annotating content to represent its structure and presentation. Examples include Markdown and XML.

metadata

Data about data. In documentation, this refers to information about the document itself added to the file, like authors, dates, tags.

open source

Software projects with publicly available source code that can be used, modified, and distributed by anyone. Provide opportunities to contribute.

OxygenXML

An XML editor and publishing platform that supports DITA and other XML formats, along with Markdown and docs-as-code workflows.

RAML

Stands for REST API Modeling Language and is similar to OpenAPI specifications. RAML is backed by Mulesoft, a commercial API company, and uses a more YAML-based syntax in the specification.

ReadTheDocs

A platform that automatically builds and deploys documentation from repositories, especially popular for open source projects.

reStructuredText (reST)

A lightweight markup language often used with Sphinx. Offers more directive capabilities than Markdown.

schematron

XML vocabulary that allows validating the structure and content in XML documents against a set of rules. Can help enforce standards.

Sphinx

A static site generator developed for managing documentation for Python. Sphinx is a documentation-oriented static site generator available that includes features such as search, sidebar navigation, semantic markup, and managed links. Based on Python.

static site generator

Tool that compiles a website from simpler text-based source files like Markdown. Popular static site generators include Jekyll, Hugo, and Sphinx. A common part of docs-as-code workflows.

taxonomy

The classification and organization of documentation content, often using tags, categories, or other metadata.

templating language

Languages like Liquid, Handlebars, or Go that allow inserting dynamic content into static templates when sites are built. Help abstract complex site generation logic.

versioning (documentation)

The practice of keeping multiple versions of documentation to align with different versions of the product or software. See also API versioning.

YAML

A human-readable data serialization format commonly used for configuration files and OpenAPI definitions. Uses indentation and whitespace for structure. Less visually noisy than JSON. Recursive acronym for YAML Ain’t No Markup Language.

These terms are all related to version control.

blame

A Git command used to display who made the last modification to each line of a file and what that modification was.

branch

A copy of the Git repository that is often used for developing new features. Usually, you work in branches and then merge the branch into the master branch when you’re ready to publish.

Bitbucket

Similar to GitHub and GitLab, Bitbucket is a platform (by Atlassian) that hosts Git repositories and facilitates collaboration, version control, and often continuous integration/continuous deployment (CI/CD).

cherry-pick

Allows you to select a specific commit from one branch and apply it onto another branch.

clone

The Git command used to copy a repository in a way that keeps it linked to the original. The first step in working with any repository is to clone the repo locally. Git is a distributed version control system, so everyone working in it has a local copy (clone) on their machines.

commit

A snapshot of your changes to the Git repo. Git saves the commit as a snapshot in time that you can revert to later if needed. You commit your changes before pulling from origin or before merging your branch within another branch.

checkout

The process of retrieving a specific revision or branch from a repository to work on locally.

fork

A personal copy of another user’s repository. This allows one to experiment with changes without affecting the original project.

Git

A distributed version control system that tracks changes to code or text files. Allows branching and merging of file updates among multiple collaborators. Core part of collaborating on software projects and docs-as-code workflows.

Git hook

Scripts that can run automatically on occurrence of specific events in a Git repository. They can be useful for automating certain tasks like code checks.

GitHub

A web-based platform built around Git that provides user interfaces and collaboration features such as wikis, issue tracking, and pull requests. Commonly used to manage documentation.

GitLab

Similar to GitHub and Bitbucket, GitLab is a platform that hosts Git repositories and facilitates collaboration, version control, and often continuous integration/continuous deployment (CI/CD).

Git repo

In Git, a repo (short for repository) stores your project’s code. Usually, you only store non-binary (human-readable) text files in a repo, because Git can run diffs on text files and show you what has changed.

HEAD

A pointer/reference to the latest commit in the branch you’re currently on.

Main branch

The primary branch where all the development is done and from where new branches are created. Previously referred to as the master branch but changed for inclusivity reasons.

merge conflict

Occurs when two branches have changes in the same part of a file, and Git cannot automatically determine which version to use.

Mercurial

A distributed revision control system, similar to Git but not as popular.

Perforce

Revision control system often used before Git became popular. Often configured as a centralized repository instead of a distributed repository.

pull

In Git, when you pull from origin (the main location where you cloned the repo), you get the latest updates from origin onto your local system.

pull request

GitHub workflow where proposed code changes in a branch are submitted for review and potential merging into the project’s main branch.

push

In Git, when you want to update the origin (the main location where you cloned the repo) with the latest updates from your local copy, you run git push. Your updates will bring origin back into sync with your local copy.

rebase

A way to integrate changes from one branch into another. It’s an alternative to merging and involves reapplying changes from one line of work onto another in a sequential manner.

remote

A reference to an external repository, typically hosted on a server, where teams collaborate on a project. It allows developers to fetch data from or push data to the external repository. The default remote is usually named ‘origin’ when you clone a repository.

stash

A temporary space to store changes that you don’t want to commit yet. This allows you to switch branches without committing your current changes.

Subversion (SVN)

Centralized version control system developed by Apache. It was one of the most popular version control systems before the rise of Git.

tag (Git)

A reference to a specific commit. Tags are typically used to capture a point in history, often used for release versions (e.g., v1.0).

version control

A system to track changes to code and documentation over time, support collaboration, and maintain previous versions. Examples are Git, SVN, Perforce. Also referred to as version control system.

webhooks

Automated messages sent when a specific event happens on a platform. In docs-as-code, often used to trigger builds or updates when changes are pushed to a repository.

These terms are all related to the writing process.

cross-reference

A link from one documentation topic to a related topic to help users navigate and find associated information.

outline

A list of section headings and bullet points that maps out the structure and content to be covered in a document. Outlines are created before writing begins.

peer review

The process where fellow technical writers or other professionals review the documentation for clarity, consistency, and accuracy.

portfolio

A collection of writing samples and projects that demonstrates a technical writer’s skills and experience. Useful for job applications.

publishing

The act of finalizing documentation and making it publicly available on a website or elsewhere. The last step of the writing process.

review

The process of having stakeholders and subject matter experts read draft documentation and provide feedback to improve the content.

stakeholder

People involved in some way with a product, such as engineers, product managers, executives, partners, support, and others. Stakeholders review documentation.

These terms are all related to OpenAPI.

$ref (OpenAPI spec)

Allows the inclusion of a piece of an OpenAPI description from another location, aiding in reusability.

API Console

Renders an interactive display for the RAML spec. Similar to Swagger UI, but for RAML. See also interactive API console.

components (OpenAPI spec)

Storage for re-usable schema definitions referenced elsewhere through $ref pointers in the OpenAPI specification.

externalDocs (OpenAPI spec)

Links to external documentation, providing more in-depth information or context about the API or specific endpoints.

info (OpenAPI spec)

Provides metadata about the API like title, description, version, and other details.

mock server

A simulated API server that returns sample responses without any actual implementation or processing of requests. Mock servers allow testing interactions with an API before it’s built.

OAS

Abbreviation for OpenAPI specification.

OpenAPI contract

Synonym for OpenAPI specification document.

OpenAPI Initiative

The governing body that directs the OpenAPI specification. Backed by the Linux Foundation.

OpenAPI specification

A vendor-neutral specification (in JSON or YAML) for describing REST APIs. Allows API providers to describe API operations, parameters, authentication methods, models, and other components in a portable document. When valid, the specification document can be used to create interactive documentation, generate client SDKs, run unit tests, and more. See also Swagger.

OpenAPI specification document

The file (either in YAML or JSON syntax) that describes your REST API. Follows the OpenAPI specification format. See also API contract

OpenAPI (Swagger)

A specification for describing REST APIs that can be used to generate interactive documentation, code libraries, and more.

parameters (OpenAPI spec)

In the OpenAPI spec, ‘parameters’ specifies the expected inputs for API operations, such as path, query, and header parameters.

paths (OpenAPI spec)

In the OpenAPI spec, ‘paths’ denote the available routes or endpoints in an OpenAPI specification.

responses (OpenAPI spec)

In the OpenAPI spec, ‘responses’ describes the expected responses from API operations.

securitySchemes (OpenAPI spec)

Defines the authentication methods used by the API, like API keys, HTTP authentication, OAuth, etc.

servers (OpenAPI spec)

Defines the base URLs for the API’s endpoints, allowing the specification to describe APIs with varying environments like development, staging, or production.

tags (OpenAPI spec)

Groups for endpoints to organize them in the interactive documentation. Used in the OpenAPI spec.

validation

The process of ensuring that an OpenAPI document adheres to the OAS specification’s structure and constraints.

These terms are all related to Swagger.

API definition

See API specification. This is the structured description of how the API functions, its endpoints, parameters, responses, and more. Swagger tools parse this definition to provide various functionalities.

Interactive API console

Provided by Swagger UI, this console allows users to make API calls directly from the documentation. This interactive feature enables developers to try out the API endpoints as they read through the docs.

Swagger

A framework for the OpenAPI specification that includes a suite of tools for auto-generating documentation, client SDK generation, and more. In contrast to the term OpenAPI, Swagger now refers to API tooling related to the OpenAPI spec. Some of these tools include Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others. These tools are managed by Smartbear. Note: Although ‘Swagger’ was the original name of the OpenAPI spec, the name was later changed to OpenAPI to reinforce the open, non-proprietary nature of the standard. OpenAPI is still often referred to as Swagger.

Swagger annotations

In-code annotations that developers can use within their codebase. When the application code is processed by Swagger tools, these annotations help auto-generate an OpenAPI specification.

Swagger Codegen

Generates client SDK code for a lot of different platforms (such as Java, JavaScript, Scala, Python, PHP, Ruby, Scala, and more). The client SDK code helps developers integrate your API on a specific platform and provides for more robust implementations that might include more scaling, threading, and other necessary code. In general, SDKs are toolkits for implementing the requests made with an API. Swagger Codegen generates the client SDKs in nearly every programming language.

Swagger Editor

An online editor that validates your OpenAPI document against the rules of the OpenAPI specification. The Swagger Editor will flag errors and give you formatting tips.

SwaggerHub

A premium API platform from Smartbear that provides collaboration, mocking, testing, and publishing tools around the OpenAPI specification.

Swagger Inspector

An online tool for testing APIs. It helps you quickly validate and inspect API requests and responses without the need for any underlying implementation.

Swagger Petstore

A basic example of an OpenAPI specification rendered by Swagger. Many people use this as a template or a reference when creating their own API specifications.

Swagger plugins

Extensions or plugins available for various frameworks and platforms to integrate Swagger capabilities into the software development workflow. Examples include Maven plugins, Gradle plugins, etc.

Swagger UI

An open-source web framework (on GitHub) that parses an OpenAPI specification document and generates an interactive documentation website. Swagger UI is the tool that transforms your spec into the Petstore-like site.

These terms are all related to project management.

acceptance criteria

Specific conditions that a user story or feature must satisfy to be accepted by the product owner or stakeholders.

backlog

In Scrum, a prioritized list of work items or user stories waiting to be worked on and completed by the team.

Backlog grooming/refinement

An ongoing process where the product owner and the Scrum team review items in the backlog to ensure they are prioritized and ready for future sprints.

daily standup

A short daily meeting, usually held in the morning, where each member of the Scrum team describes what they accomplished yesterday, plans for today, and any blocking issues.

definition of done

In Scrum, the agreed upon criteria that user stories must meet before they can be considered complete and shippable.

epic

A large user story that can be broken down into smaller stories, used in Agile software development to group related functionality.

iteration

Synonymous with sprint.

Kanban

An agile project management methodology that uses a board with columns for tracking the progress of work through different states.

product owner

In Scrum, the person responsible for maintaining the product backlog, setting priorities, and ensuring the team delivers maximum value to the stakeholders.

release planning

A longer-term planning meeting where the team determines which features or user stories are targeted for an upcoming release.

Scrum

An agile project management framework that breaks down product development into short, iterative sprints with daily standup meetings.

sprint

In Scrum, a short, timeboxed period (usually 1-4 weeks) focused on completing specific work items for a product increment.

sprint demo

A meeting at the end of each sprint where the Scrum team shows completed user stories/features to stakeholders and collects feedback.

sprint planning

A meeting at the start of each sprint where the product owner and team select user stories from the backlog to work on that align with the sprint goal.

sprint retrospective

A meeting at the end of each sprint where the Scrum team reflects on what went well, what needs improvement, and lessons learned from the sprint.

stakeholder engagement

The process of involving all parties that have an interest in the project, ensuring their feedback and concerns are considered.

story points

A unit of measure for expressing the overall size, complexity, and effort required to implement a user story or feature in Agile methodologies like Scrum.

timeboxing

Allocating a fixed amount of time for an activity. Used in Scrum for meetings and sprints to ensure they don’t overrun.

T-shaped skills

The concept that members of the team should have deep expertise in a specific discipline (the vertical line of the T) and broad skills and knowledge across many disciplines (the horizontal line of the T). This encourages collaboration and flexibility within teams.

user story

A high-level definition of a requirement or feature from an end-user perspective, used as the basis for planning in Agile methodologies.

velocity

In Scrum, the amount of work a team can successfully complete within a sprint, measured in story points. Used to forecast how much work can be done.

waterfall

A sequential, linear software development methodology where phases must be completed in order before moving to the next phase.

Work in Progress (WIP)

In Kanban, a limit set to restrict the number of items being worked on simultaneously. It ensures that teams are not overwhelmed and can maintain focus.

These terms are all related to testing and quality assurance.

accessibility testing

Ensuring that documentation is usable and understandable by people with disabilities, in compliance with standards like the Web Content Accessibility Guidelines (WCAG).

agile testing

Relying on user feedback after release to improve docs iteratively. Risky without pre-release testing.

assumption

An idea taken for granted without confirmation. Docs often make faulty assumptions about user knowledge.

beta testing

Testing done by real users in their real environment before the final release. Feedback from beta testing can highlight issues in both the product and the associated documentation.

bug

A defect or issue in the product or documentation. Bugs raised in documentation might pertain to factual inaccuracies, unclear instructions, or missing content.

feedback loop

A process for continuously gathering and integrating feedback into documentation, typically using comments, surveys, or direct user input.

localization testing

Ensuring that the translated versions of documentation are accurate, culturally appropriate, and align with the original intent of the content.

QA

Quality Assurance. Team responsible for testing products before release to ensure quality.

regression testing

Testing conducted to ensure that recent changes or updates haven’t negatively impacted the existing documentation or functionality.

smoke test

Preliminary testing to catch the most glaring and obvious errors in documentation, such as broken links or missing pages.

test case

A scenario to execute to validate expected behavior and responses. QA teams run test cases.

test environment

The system setup used to experiment with and validate code, APIs, apps, etc. Often a separate test server.

usability testing

A method to evaluate the effectiveness and clarity of documentation by observing real users as they try to achieve tasks using the documentation.

user testing

Having real users try documentation to identify problems and gaps. Essential for creating usable docs.

These terms are all related to conceptual documentation.

authorization documentation

Instructions and details on how users can obtain access credentials and authenticate their requests to the system. Crucial for APIs that require secure access.

code sample

Practical, executable examples in various programming languages that show how to use specific features or accomplish tasks with the product.

conceptual docs

Explains foundational ideas, giving readers a sense of the bigger picture. Guides users in understanding the underlying principles and concepts of the technology or product.

error message documentation

Explanations for potential errors users might encounter, offering solutions or workarounds to address these issues.

getting started tutorial

A beginner’s guide aimed at helping users achieve their first success with the product or technology. Simplifies the initial experience and encourages deeper exploration.

product overview documentation

Introductory content that offers a bird’s-eye view of the product, its main features, and benefits. It sets the stage for users, helping them understand what the product is and why it matters.

quick reference

A condensed sheet or guide that highlights the most important elements, often used for quick consultations or reminders.

rate limiting and thresholds documentation

Guidelines on the number of requests users can make within a specified time frame, ensuring the system remains responsive and available to all users.

reference docs

Detailed documentation of an API’s resources/endpoints, parameters, sample requests, responses, errors, etc. Provides a reference for developers.

release notes

Updates accompanying each new version of the product, detailing the additions, changes, bug fixes, and any other relevant information.

support

Resources that help API users, often provided through live chat, forums, or ticketing systems.

terminology

Specialized words and phrases used in a field. See glossary.

tutorial

Detailed guides focused on teaching users how to achieve specific tasks. Broken down step-by-step, often accompanied by screenshots, code snippets, or videos.

These terms are all related to API tools and platforms.

API Transformer

A cross-platform service provided by APIMATIC that will automatically convert your specification document from one format or version to another. See apimatic.io/transformer.

Apiary

Platform that supports the full life-cycle of API design, development, and deployment. For interactive documentation, Apiary supports the API Blueprint specification, which is similar to OpenAPI or RAML but includes more Markdown elements. It also supports the OpenAPI specification now too. See apiary.io.

Apigee

Similar to Apiary, Apigee provides services for you to manage the whole lifecycle of your API. Specifically, Apigee lets you ‘manage API complexity and risk in a multi- and hybrid-cloud world by ensuring security, visibility, and performance across the entire API landscape.’ Supports the OpenAPI spec. See apigee.com.

APIMATIC

Supports most REST API description formats (OpenAPI, RAML, API Blueprint, etc.) and provides SDK code generation, conversions from one spec format to another, and many more services. For example, you can automatically convert Swagger 2.0 to 3.0 using the API Transformer service on this site.

Blobr

A cloud platform for creating API portals that package API use cases into purchasable products with customized documentation. Allows monetizing APIs.

customization

Changing the default styling and branding of a platform. Blobr enables customizing the portal name, logo, colors, domain, etc.

Mulesoft

Similar to Apiary or Apigee, Mulesoft provides an end-to-end platform for designing, developing, and distributing your APIs.

monetization

Generating revenue from an API, through methods like usage fees, rate limits, subscriptions, or freemium models.

Postman

A GUI application for interacting with APIs by constructing requests and viewing responses. Simplifies API testing. Useful for exploring and trying out APIs.

RAML Console

In Mulesoft, the RAML Console is where you design your RAML spec. Similar to the Swagger Editor for the OpenAPI spec.

Redoc

An open-source tool for generating interactive API reference documentation from OpenAPI (formerly Swagger) definitions. Provides an expandable three-column layout.

Redocly

Company that offers premium tools and services for API documentation, including enhanced Redoc, CLI tools, and developer portals.

Repo

A tool for consolidating and managing many smaller repos with one system.

Smartbear

The company that maintains and develops the Swagger tooling, such as Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others.

Stoplight

Provides a platform with visual modeling tools to create an OpenAPI document for your API — without requiring you to know the OpenAPI spec details or code the spec line by line.