1. I'd Rather Be Writing
2. Docs
3. Chapter 17: Glossary

Chapter 17: Glossary

The API documentation landscape is full of jargon, acronyms, and many new terms. This glossary provides a list of terms and definitions.

A

agile testing

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

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 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.

API Console

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

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 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 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.

Asciidoc

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

assumption

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

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.

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.

B

backlog

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

Blobr

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

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.

C

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.

code sample

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

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.

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.

continuous delivery

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

cross-reference

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

CRUD

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

curl

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

customization

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

D

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.

DELETE

An HTTP method that removes a resource.

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.

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.

E

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.

epic

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

error message documentation

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

G

GET

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

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.

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.

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.

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.

H

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.

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.

header parameters

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

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 verb

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

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.

J

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.

K

Kanban

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

M

Markdown

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

Mercurial

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

metadata

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

method

An HTTP verb that indicates the desired action for an API request. Common HTTP methods are GET, POST, PUT, and DELETE.

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.

monetization

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

Mulesoft

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

N

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.

O

OAS

Abbreviation for OpenAPI specification.

open source

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

OpenAPI (Swagger)

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

OpenAPI contract

Synonym for OpenAPI specification document.

OpenAPI Initiative

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

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 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.

operation

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

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.

OxygenXML

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

P

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 {}.

paths

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

payload

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

Perforce

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

portfolio

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

POST

An HTTP method that creates a new resource.

Postman

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

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.

publishing

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

pull request

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

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.

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.

PUT

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

Q

QA

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

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 &.

quick reference

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

R

RAML Console

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

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.

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.

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.

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.

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.

Repo

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

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

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

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.

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 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.

response

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

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.

review

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

S

schematron

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

Scrum

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

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.

Smartbear

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

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.

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.

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.

SwaggerHub

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

T

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.

terminology

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

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.

thematic analysis

A qualitative data analysis method that involves identifying, analyzing, and reporting patterns or themes within data. Useful for synthesizing insights with AI tools.

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.

U

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.

user testing

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

V

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.

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.

W

waterfall

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

Y

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.