Core Concepts

Essential terms and concepts for API documentation. This section defines foundational terminology encountered when documenting APIs, from basic architectural principles to documentation standards that apply across different API types.

API Fundamentals

API

Definition: acronym for application programming interface

Application: software for end-users - not operating, administering or programming a computer
Program: sequence of instructions for a computer to perform, often stored in a file
Interface: program that runs on a computer and provides resources for other computers, programs, or services, also known as the server

Purpose: enables resource sharing - how one program or service uses the resources of another program or service, in which the resources are program functions, data, or shared devices that with other computers

Every API description must describe:

What the program wants: procedure name, URL of resource
Where they want it from: address/location of the procedure or resource
How they want it: parameters to change or specify aspects of the request; response must be predictable for the program to use it effectively

Why documentation matters:

acts as the contract between resources and programs using them
without documentation, crossing the interface likely fails
enables programmers to contruct correct code
prevents developers from needing to reverse-engineer, which is often prohibited by license

Example API request/response flow:

Related Terms: API endpoint, API gateway, API security, REST API

Source: UW API Docs: Module 5, Lesson 1, "REST API Fundamentals"

API endpoint

Definition: specific URL where an API can access resources; the touchpoint where clients interact with the API server to perform operations

Purpose: define the structure of API requests and enable developers to access specific resources or perform specific actions; each endpoint represents a distinct function or resource in the API

Key characteristics:

URL structure: combines base URL with resource path
HTTP method: defines the operation - GET, POST, PUT, DELETE
Unique purpose: each endpoint performs a specific function

Example:

https://api.example.com/v1/users/123

Breaking down this endpoint:

Base URL: https://api.example.com
Version: /v1
Resource path: /users/123
Action: determined by HTTP method
GET retrieves user 123 while DELETE removes user 123

Common endpoint patterns:

Pattern	Purpose	Example
`/resource`	Collection operations	`GET /users` lists all users
`/resource/{id}`	Single resource operations	`GET /users/123` retrieves one user
`/resource/{id}/subresource`	Related resources	`GET /users/123/orders`

Related Terms: API, HTTP, HTTP method, parameters, request/response, resource, REST API

Source: UW API Docs: Module 5, Lesson 1, "REST API Fundamentals"

API security

Definition: measures taken to protect APIs from unauthorized access, misuse, and attacks

Why security matters: APIs are commonly used to enable access to sensitive software functions and data - in result, they're becoming an increasingly desired target for attackers

authentication

Definition: determines who users are - a technique invented to overcome the weakness of shared credentials; an API authentication key is commonly a long series of numbers and letters that's included in a request header or request URL

authorization

Definition: determines what users can do - confirms users are who they claim to be by using techniques such as checking ID to verify identity

Related Terms: API, error handling, HTTPS, rate limiting, validation

Source: UW API Docs "Intentional Outcomes," Canvas Forum Thread

CRUD

Definition: acronym for "Create, Read, Update, Delete"; the four basic operations for persistent storage and data management in APIs

Purpose: provides a standard framework for API operations that maps directly to HTTP methods, making API design intuitive and predictable; CRUD operations form the foundation of most REST API interactions

HTTP method mapping:

CRUD Operation	HTTP Method	Action	Example
Create	`POST`	Add new resource	`POST /users` creates a new user
Read	`GET`	Retrieve resource	`GET /users/123` retrieves user 123
Update	`PUT` or `PATCH`	Change resource	`PUT /users/123` edits entire user record
Delete	`DELETE`	Remove resource	`DELETE /users/123` removes user 123

Example: a typical CRUD API for managing blog posts supports creating new posts via POST /posts, reading posts via GET /posts/{id}, updating posts via PUT /posts/{id}, and deleting posts via DELETE /posts/{id}

Related Terms: DELETE, GET, HTTP method, PATCH, POST, PUT, resource, REST API

Sources:

Mozilla Corporation, MDN: "HTTP request methods"
UW API Docs: Module 2, Lesson 5: "Create a Master Prompt"

`DELETE`

Definition: HTTP method that requests removal of a specified resource from the server

Purpose: enables clients to delete records, remove files, or clean up resources through standardized HTTP operations

Example: sending DELETE /api/users/123 removes the user account with ID 123 from the system

Related Terms: GET, HTTP method, PATCH, POST, PUT

Source: Mozilla Corporation, MDN: "DELETE request method"

error handling

Definition: the process of anticipating, detecting, and responding to errors that occur during API operations; includes both how the API communicates errors and how clients should handle them

Purpose: enables developers to build robust applications that gracefully handle failures, provide meaningful feedback to users, and recover from issues; good error handling documentation explains which errors can occur, what they mean, and how to resolve them

Example: when a client sends invalid data in a POST request, the API returns a 400 Bad Request status code with a JSON response body that specifies which fields are invalid and why:

Common Pattern:

{
  "error": "Bad Request",
  "message": "Invalid email format"
}

Note: This is the most widely used format, though field names vary error, code, message, etc.

RFC 9457:

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Invalid email format",
  "instance": "/users/123"
}

Note: This is a standardized format that provides machine- readable error types and more context; uses application/problem+json media type; less common but increasingly adopted by modern APIs; only required field is type, defaults to "about:blank"

Related Terms: API, HTTP status codes, JSON, rate limiting, troubleshooting, validation

Sources:

`GET`

Definition: HTTP method that requests data from a server without modifying any resources; the most common method for retrieving information

Purpose: enables clients to read data, view resources, or query information while ensuring the request remains safe and idempotent

Example: sending GET /api/users/123 retrieves information about the user with ID 123 without changing any data

Related Terms: DELETE, HTTP method, idempotent, PATCH, POST, PUT

Source: Mozilla Corporation, MDN: "GET request method"

HTTP

Definition: acronym for Hypertext Transfer Protocol; synchronous request/response protocol that enables communication between clients and servers over the web; defines message format and transmission type, and how web servers and browsers should respond to a variety of commands

Purpose: HTTP forms the foundation of API communication; understanding HTTP is essential for documenting API endpoints, request methods- GET, POST, PUT, DELETE - status codes, headers, and error handling; most RESTful APIs rely on HTTP as their underlying protocol

Example: when a user submits a form on a website, the browser sends an HTTP POST request to the server with the form data; the server processes the request and returns an HTTP response with a status code, such as 200 for success or 400 for a bad request, and any relevant data

Source: IETF RFC 9110 - HTTP Semantics

HTTP method

Definition: verb that indicates the desired action to perform on a resource in an HTTP request; defines what operation the client wants the server to execute

Purpose: provides standardized semantics for API operations, making it clear whether a request reads, creates, updates, or deletes data

Example: REST APIs use methods like GET for reading, POST for creating, PATCH for editing specific fields, PUT for updating whole resources, and DELETE for removing resources

Related Terms: CRUD, DELETE, GET, HTTP, PATCH, POST, PUT

Source: Mozilla Corporation, MDN: "HTTP request methods"

HTTPS

Definition: acronym for Hypertext Transfer Protocol Secure; encrypts communication between clients and servers using Transport Layer Security - TLS, or its predecessor, Secure Sockets Layer - SSL; HTTPS protects data from interception and tampering during transmission through encryption - the process of encoding data so only authorized parties can read it

Purpose: HTTPS is critical for API security documentation; all modern APIs should use HTTPS to protect sensitive data like authentication tokens, user credentials, and personal information; API documentation must specify HTTPS endpoints and explain security requirements

Security Note: while HTTPS provides security, it's not an API security measure or technique, but a protocol implementation; security is one aspect of HTTPS, but not its defining characteristic

Example: when users log into a banking app, their credentials travel over HTTPS; the encrypted connection ensures that even if someone intercepts the network traffic, they can't read the username, password, or account information

Related Terms: API security, authentication, HTTP, HTTP versions

Source: IETF RFC 9110 - HTTP Semantics

HTTP status codes

Definition: three-digit codes returned by servers in HTTP responses that show whether a specific request succeeded or failed, and why

Purpose: status codes enable developers to handle different response scenarios appropriately, add proper error handling, and debug API issues; API documentation must explain which status codes an endpoint returns and what they mean

Status code categories:

Code Range	Category	Meaning
1xx	Informational	Request received, continuing process
2xx	Success	Request successfully received, understood, and accepted
3xx	Redirection	Further action needed to complete the request
4xx	Client Error	Request contains bad syntax and/or server can't process
5xx	Server Error	Server failed to fulfill an apparently valid request

Common status codes:

Code	Label	Meaning
`200`	`OK`	Request succeeded
`201`	`Created`	New resource successfully created
`204`	`No Content`	Request succeeded but no content to return
`400`	`Bad Request`	Server can't process due to client error
`401`	`Unauthorized`	Authentication required or failed
`403`	`Forbidden`	Server understood but refuses to process
`404`	`Not Found`	Requested resource doesn't exist
`500`	`Internal Server Error`	Server encountered an unexpected condition
`503`	`Service Unavailable`	Server temporarily unable to handle request

Client requests a user that doesn't exist:

GET https://api.example.com/users/999

Response:

{
  "status": 404,
  "error": "Not Found",
  "message": "User with ID 999 does not exist"
}

Source: IETF RFC 9110 - HTTP Semantics

HTTP versions

Definition: iterations of the Hypertext Transfer Protocol with different performance and feature capabilities; HTTP/1.1 (1997) uses sequential requests, HTTP/2 (2015) enables concurrent requests over one connection, HTTP/3 (2022) uses QUIC protocol - originally "Quick UDP Internet Connections," now just QUIC - for improved reliability

Purpose: understanding version differences helps explain why certain API architectures like gRPC require specific HTTP versions for their performance characteristics

Example: a gRPC API requires HTTP/2 because it relies on features like multiplexing and bidirectional streaming that aren't available in HTTP/1.1

Related Terms: gRPC API, HTTP, HTTPS, REST API

Source: IETF RFC 9110 - HTTP Semantics

idempotent

Definition: describes an operation that produces the same result regardless of how many times it's executed; making the same request many times has the same effect as making it once

Purpose: enables safe request retries without unintended side effects; critical for network reliability when timeouts and/or connection issues risk request duplication

Example: DELETE /users/123 is idempotent as deleting the same user many times results in the same state: "user deleted" - while POST /users isn't idempotent, as posting the same user data many times creates many user records

HTTP methods & idempotency:

Method	Idempotent	Reason
`DELETE`	Yes	Deleting an already-deleted resource has same outcome
`GET`	Yes	Reading data doesn’t change server state
`PATCH`	Depends	Partial updates may or may not be idempotent based on implementation
`POST`	No	Creating resources many times produces different results
`PUT`	Yes	Replacing a resource with the same data produces identical result

Related Terms: DELETE, GET, HTTP method, POST, PUT

Source: IETF RFC 9110 - HTTP Semantics: Section 9.2.2

JSON

Definition: acronym for JavaScript Object Notation; a lightweight, text-based data format that uses human-readable key-value pairs to represent structured data

Purpose: provides an efficient way to exchange data between clients and servers; JSON has become the dominant format for modern REST APIs due to its readability, compact size, and native compatibility with JavaScript

Key characteristics:

Objects: collections of key-value pairs enclosed in curly braces {}
Arrays: ordered lists of values enclosed in square brackets []
Values: can be strings, numbers, booleans, null, objects, or arrays
Properties: keys that identify values within objects

Example:

{
  "id": 123,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "active": true,
  "roles": ["user", "admin"],
  "address": {
    "street": "123 Main St",
    "city": "Seattle",
    "state": "WA"
  }
}

Common API use cases:

Use Case	Example
Request body	Sending data in `POST` or `PUT` requests
Response body	Returning data from API endpoints
Configuration	Storing API settings and options
Error messages	Structured error information

Related Terms: payload, REST API, serialization, XML

Source: JSON.org: "Introducing JSON"

parameters

Definition: variables passed in API requests to specify or filter the data returned, change behavior, or provide necessary information for the operation

Purpose: parameters enable flexible, precise API requests without requiring separate endpoints for every variation; API documentation must describe each parameter's purpose, data type, whether it's required or optional, and valid values

Parameter types:

Type	Location	Purpose	Example
Path parameters	In the URL path	Identify specific resources	`/users/{id}`
Query parameters	After `?` in URL	Filter, sort, or paginate results	`/users?role=admin&limit=10`
Header parameters	HTTP headers	Authentication, content type	`Authorization: Bearer token123`
Body parameters	Request body	Complex data for `POST/PUT`	JSON object with user details

Example using many parameter types:

GET https://api.example.com/v1/users/123/orders?status=pending&limit=5
Authorization: Bearer abc123xyz

Breaking down the parameters:

Path parameter: 123 - user ID
Query parameters: status=pending and limit=5
Header parameter: Authorization: Bearer abc123xyz

Documentation requirements for each parameter:

Name and data type - string, integer, boolean
Whether it's required or optional
Valid values or format
Default value if applicable
Description of what it does

Related Terms: API endpoint, request/response, REST API

Source: UW API Docs: Module 5, Lesson 1, "REST API Fundamentals"

payload

Definition: the actual data transmitted in an API request or response body, excluding headers and metadata; contains the information sent and/or received

Purpose: distinguishes the meaningful content from the technical transmission details; understanding payload structure is essential for API documentation as it defines what data clients send and receive

Example: in a POST /users request, the payload contains the data required to create a user:

{
  "firstName": "Alice",
  "lastName": "Smith",
  "email": "alice@example.com",
  "role": "developer"
}

Common payload formats:

Format	Use Case	Example
JSON	Most REST APIs	`{"name": "value"}`
XML	Legacy systems, SOAP	`<name>value</name>`
Form data	File uploads, form submissions	`name=value&email=user@example.com`
Binary	File transfers, images	Raw bytes

Related Terms: HTTP method, JSON, request/response, REST API, serialization, XML

Sources:

Mozilla Corporation, MDN: "HTTP Messages"
UW API Docs: Module 2, Lesson 5: "Create a Master Prompt"

`PATCH`

Definition: HTTP method that applies partial modifications to an existing resource; sends only the fields that need updates rather than the entire resource

Purpose: enables clients to update specific fields of a resource efficiently without sending unchanged data; reduces bandwidth usage and streamlines updates when only a few fields need modification

Example: sending PATCH /api/users/123 with a JSON body containing {"email": "newemail@example.com"} updates only the email field of user 123, leaving other fields like name and phone_number unchanged

Related Terms: DELETE, GET, HTTP method, POST, PUT

Source: Mozilla Corporation, MDN: "PATCH request method"

`POST`

Definition: HTTP method that submits data to a server to create new resources or trigger actions; submission data typically includes a request body

Purpose: enables clients to add new records, submit forms, upload files, or execute operations that change server state

Example: sending POST /api/users with a JSON body containing {"name": "Alice", "email": "alice@example.com"} creates a new user account

Related Terms: DELETE, GET, HTTP method, PATCH, PUT, webhook API

Source: Mozilla Corporation, MDN: "POST request method"

`PUT`

Definition: HTTP method that replaces an existing resource with new data or creates a resource at a specific URL if it doesn't exist

Purpose: enables clients to update entire resources with complete replacement semantics; differs from PATCH which performs partial updates

Example: sending PUT /api/users/123 with a complete user object replaces all existing data for user 123 with the new data

Related Terms: DELETE, GET, HTTP method, idempotent, PATCH, POST

Source: Mozilla Corporation, MDN: "PUT request method"

rate limiting

Definition: mechanism that restricts the number of API requests a client can make within a specified time window; protects servers from overload and ensures fair resource distribution

Purpose: prevents abuse, maintains service stability, and ensures fair access for all users; API documentation must explain rate limits, how they're enforced, and what happens as they're exceeded

Security Implications: rate limiting is a fundamental operational and/or data handling concept that affects all API usage - not just security scenarios; it's about resource management, fair access, and system stability as much as it's about preventing abuse

Common rate limiting patterns:

Pattern	Description	Example
Fixed window	Set number of requests per time unit	1000 requests per hour
Sliding window	Rolling time window for more precision	1000 requests per 60-minute window
Token bucket	Requests consume tokens that regenerate	10 tokens/second, burst up to 100
Per-user	Limits apply to individual users/keys	100 requests/minute per API key

Example: an API with rate limiting returns 429 Too Many Requests when a client exceeds the rate limit, along with headers indicating when the client can retry:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704398400
Retry-After: 3600

Sources:

IETF RFC 6585 - Additional HTTP Status Codes: Section 4
Mozilla Corporation, MDN: "429 Too Many Requests"
UW API Docs: Module 2, Lesson 5, "Create a Master Prompt"

request/response

Definition: the two-part communication pattern in API interactions where a client sends a request to a server and receives a response

Purpose: understanding the request/response cycle is fundamental to using and documenting APIs; documentation must show what requests look like, what data to include, and what responses to expect

Request components:

Component	Description	Example
HTTP method	Action to perform	`GET`, `POST`, `PUT`, `DELETE`
Endpoint URL	Resource location	`https://api.example.com/users`
Headers	Metadata about the request	`Content-Type: application/json`
Body	Data sent with request - `POST/PUT`	JSON object
Parameters	Request specifications	Query or path parameters

Response components:

Component	Description	Example
Status code	Outcome of the request	`200`, `404`, `500`
Headers	Metadata about the response	`Content-Type: application/json`
Body	Data returned from server	JSON object

Example request:

POST https://api.example.com/users
Content-Type: application/json
Authorization: Bearer token123

{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 456,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "created_at": "2025-12-30T10:30:00Z"
}

Related Terms: API endpoint, HTTP, HTTP method, HTTP status codes, parameters, REST API

Source: UW API Docs: Module 5, Lesson 1, "REST API Fundamentals"

resource

Definition: a distinct piece of data or entity available for reference or modification through an API; REST architecture fundamental concept in which everything is a resource with a unique identifier

Purpose: provides a consistent mental model for API design and usage; resources map to real-world entities and enable intuitive API structures where URLs represent resources and HTTP methods represent actions on those resources

Key characteristics for each resource:

Unique identifier: has a distinct URI or ID
Representations: return in different formats like JSON or XML
State: have properties available for reading or updating
Relationships: can relate to other resources

Common resource types:

Type	Example	Typical Operations
Collection	`/users`	List all, create new
Individual	`/users/123`	Read, edit, delete one
Nested	`/users/123/orders`	Access related resources
Singleton	`/profile`	Read or change single instance

Example: in an e-commerce API, resources include users, products, orders, and payments; each resource type has its own endpoint structure like /products/456 for a specific product resource

Related Terms: API endpoint, CRUD, HTTP method, REST API, URI, URL

Sources:

IETF RFC 9110 - HTTP Semantics: Section 3.1
UW API Docs: Module 2, Lesson 5: "Create a Master Prompt"

schema

Definition: also know as the Schema Object, the formal definition that describes the structure, data types, constraints, and relationships within an API's requests and responses

Purpose: enables validation, auto-generated documentation, and type safety; helps both API providers and consumers understand exactly what data format to expect

Example: an OpenAPI schema defines that a POST /users endpoint requires a request body with string type for email field and integer type for age field

Sources:

serialization

Definition: the process of converting data structures and/or objects into a format appropriate for network transmission or storage, then reconstructed later

Purpose: enables data exchange between systems by transforming programming language objects into formats like JSON, XML, or binary that can travel across network boundaries

Example: serializing a JavaScript user object {name: "Alice", age: 30} into JSON string {"name":"Alice", "age":30} before sending it in an API request

Related Terms: JSON, payload, protocol buffers, XML

Source: Mozilla Corporation, MDN: "Serialization"

URI

Definition: acronym for Uniform Resource Identifier; standard format for identifying resources in a way that enables consistent reference across different systems; identifies a resource but doesn't necessarily specify how to locate or access it

Purpose: provides a unified way to name resources regardless of their location or access method; forms the foundation for both URLs and URNs - Uniform Resource Names - creating a consistent identification system across the web

Example: mailto:user@example.com is a URI that identifies an email address resource; urn:isbn:0-486-27557-4 is a URI that identifies a book by its ISBN - International Standard Book Number; both identify resources without specifying network locations

Related Terms: API endpoint, HTTP, resource, REST API, URL

Source: IETF RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax

URL

Definition: acronym for Uniform Resource Locator; specific URI type that not only identifies a resource but also provides the means to locate it on a network by describing its primary access mechanism and network location

Purpose: enables clients to locate and retrieve resources over the web; essential for API documentation as URLs define exactly where endpoints exist and how to reach them

Example:

https://api.example.com:443/v1/users/123?include=orders

Break down this URL:

Category	Component	Example	Description
how	schema	`https://`	protocol for accessing the resource
where	host	`api.example.com`	server location
optional	port	`:443`	HTTPS default, directs traffic
what	endpoint/path	`/v1/users/123`	specific resource location
optional	query parameters	`?include=orders`	request modifications

Related Terms: API endpoint, HTTP, parameters, resource, REST API, schema, URI

Sources:

validation

Definition: process of checking whether data meets specified rules, constraints, and format requirements before processing or storage

Purpose: ensures data quality, prevents errors, and protects systems from invalid input; improves API reliability by catching problems early

Security Implications: validation is a fundamental operation that happens on every request regardless of security context - even authenticated and authorized users need their input validated; while primarly a core data handling concept, validation can also prevent injection attacks and enforce data constraints

Example: validating that an email field contains a properly formatted email address and that an age field contains a positive integer before creating a user account

Related Terms: API security, error handling, HTTP status codes, rate limiting, schema

Sources:

Documentation-specific Concepts

API overview topic

Definition: also known as "the landing page" in which the audience is everyone

Common use cases:

Not aware of API: readers researching new options or products
Aware of API: readers looking for more specific information

Reader's goals:

become aware of the product
learn more about the product
navigate to other documentation about the product

Key characteristics:

a value proposition, a tagline
CTAs, call-to-action, as in "Get Started," "Contact Us," and/or "Learn More"
links to common destinations such as "Docs," "FAQ," "Reference," and/or "Support"

When designing user-centered API overview topics:

consider the audience and their goals, and consider many users, use cases and goals
how readers might use the overview topic, "might adding or removing this content help the reader achieve their goal?"
determine how visual design and branding might be significant

Topic ↔ Reader ↔ Doc Relationships

Topic Type	Reader Goal	Doc Task
Overview, Landing Page	Awareness	Attract
First-use, Quickstart	Awareness	Attract
Tutorials, Examples	Adoption, Application	Exhibit, Apply
Conceptual	Learn	Teach
Reference	Delivery, Maintenance	Assist

API Documentation Stages ↔ User Journeys:

Source: UW API Docs: Module 6, Lesson 1, "API Documentation Overview Topics"

API reference topic

Definition: also known as "getting finished topics" - documentation that describes specific aspects of an API operation or object

Audience: people using or considering using the API

Common use cases:

Quick reference: API reference topics remember the details so developers don't have to
Research: determine the API's utility, usability, and suitability

Reader's goals:

Look up information and get back on task quickly
Assess whether the API fits their needs

Standard contents:

Element	Purpose
Title	Confirms you're in the right place
Endpoint or URL	How to call it
Description	What it does
Properties	What it contains
Property descriptions	Details about each property
Operations	Available actions, such as `GET`, `POST`
Examples	Sample requests and responses
Related links	Navigation to related topics

Related Terms: API overview topic, OpenAPI specification, reference

Source: UW API Docs: Module 6, Lesson 1, "API Documentation Overview Topics"

concept

Definition: documentation topic type; explains what something is, how it works, or why it matters; provides understanding without instructing readers to perform specific tasks

Purpose: builds foundational knowledge that helps readers understand the context, principles, and reasoning behind features or systems; concept topics answer "what" and "why" questions at an accessible, introductory level

Key Characteristics:

explains ideas, principles, or components at a foundational level
provides context and background information
avoids step-by-step instructions
may include diagrams, analogies, or examples to illustrate concepts
typically more standalone, focused on building knowledge without explicit connections to procedural content

Scope: concept topics provide introductory-level understanding, offering the essential knowledge readers need to grasp what something is and why it matters before diving deeper

Example: a concept topic about API authentication explains what authentication is, why it's necessary for API security, and how different authentication methods compare, without providing setup instructions

Source: GitLab Docs: "Concept topic type"

explanation guide

Definition: documentation topic type; clarifies a single topic in depth without providing step-by-step instructions; focuses on comprehensive understanding of concepts, principles, or features rather than completing tasks

Purpose: builds in-depth knowledge that helps readers understand how and why something works; enables users to get the most value from a product by providing extensive context and conceptual background that goes beyond foundational understanding

Key Characteristics:

explains concepts rather than procedures with greater depth than concept topics
no step-by-step instructions
may include diagrams, code examples, or real-life scenarios
explicitly links to related how-to guides, tutorials, or getting started guides
helps readers understand the "what" and "why" at a comprehensive level
serves as a bridge between understanding and doing

Scope: explanation guides provide comprehensive, in-depth understanding that goes beyond introductory concepts, offering the extensive context needed to fully grasp how systems work and make informed decisions

Example: an explanation guide about API rate limiting explains what rate limiting is, why it exists, how different rate limiting algorithms work, when to use each approach, and the trade-offs between them - without providing setup instructions but linking to implementation guides

Related Terms: concept, getting started, how-to guide, introduction, reference, tutorial

Source: Squarespace Engineering: "Part 1: Learn The Different Types Of Technical Documentation"

getting started

Definition: documentation topic type; also known as "get started" - comprehensive onboarding documentation that helps new users complete their first meaningful interaction with a product or feature; provides detailed setup, configuration, and foundational knowledge

Purpose: reduces time-to-value by guiding users through essential setup and first use; builds confidence and momentum for deeper engagement with the product through thorough, step-by-step guidance

Key Characteristics:

covers complete setup and configuration process
assumes minimal prior knowledge
provides clear, sequential steps with explanations
includes prerequisites and troubleshooting
often spans many pages or sections
balances depth with accessibility

Onboarding Topics Comparison:

Aspect	Introduction	Getting Started	Quickstart
Purpose	Awareness	Foundation building	Immediate action
Action required	None	Yes - comprehensive	Yes - minimal
Length	Variable	Longer - Many pages	Shortest - single page
Depth	Conceptual only	Detailed guidance	Essential steps only
Audience	All levels	New users	Experienced users
Content	What and why	Setup → config → examples	Fastest path to success

Example: a getting started guide for an API walks through obtaining API credentials, installing required libraries, configuring authentication, understanding key concepts, making many API calls with different parameters, and interpreting different response types

Sources:

glossary

Definition: documentation topic type; alphabetically organized collection of terms and their definitions; provides quick reference for terminology specific to a product, domain, or technology

Purpose: establishes consistent vocabulary, reduces confusion, and helps readers understand specialized terms without interrupting their workflow to search elsewhere

Key Characteristics:

terms listed alphabetically
concise, clear definitions
may include links to related terms or detailed concept topics
focused on domain-specific or product-specific terminology

Example: an API glossary defines terms like "endpoint," "rate limiting," and "webhook" with brief explanations and links to detailed documentation

Related Terms: concept, reference

Source: GitLab Docs: "Glossary topic type"

how-to guide

Definition: documentation topic type; step-by-step instructions for completing a specific real-world task; limited to a single task without detailed conceptual explanations

Purpose: enables users to complete a practical task successfully; provides focused, action-oriented guidance for readers who know what they want to achieve

Key Characteristics:

focused on a single, specific task
provides numbered steps in sequence
minimal conceptual explanation
often links to explanation guides for deeper context
assumes basic familiarity with the product

Example: a how-to guide titled "Add OAuth authentication to your API" provides the exact steps to configure OAuth without explaining authentication concepts in depth

Related Terms: explanation guide, getting started, quickstart, task, tutorial

Source: Squarespace Engineering: "Part 1: Learn The Different Types Of Technical Documentation"

introduction

Definition: broad overview documentation that explains what a product or feature is, why it exists, and what problems it solves; provides context without requiring hands-on action

Purpose: builds awareness and understanding; helps readers determine if the product meets their needs before investing time in setup or implementation

Key Characteristics:

focuses on the "what" and "why"
no step-by-step instructions
often includes use cases, benefits, and high-level architecture
may appear as landing page or overview topic content
suitable for all experience levels

Example: an API introduction explains what the API does, which problems it solves, key features, and typical use cases without providing setup instructions or code examples

Sources:

onboarding guide

Definition: documentation topic type; handbook for new team members that provides broader understanding of team systems, processes, and practices; helps teammates gain necessary context to work effectively

Purpose: enables new team members to complete essential setup and understand team workflows, tools, and conventions; reduces time-to-productivity for new hires

Key Characteristics:

comprehensive coverage of team-specific information
combines setup tasks with team context
may include checklists and milestones
targets new team members specifically
often covers tools, processes, coding standards, and team culture

Example: an engineering onboarding guide walks new developers through setting up their development environment, understanding the team's Git workflow, learning deployment processes, and accessing team resources

Related Terms: getting started, how-to guide, runbook, tutorial

Source: Squarespace Engineering: "Part 1: Learn The Different Types Of Technical Documentation"

OpenAPI Specification

Definition: also known as the OAS, a standard, language-agnostic way to define the interface of an HTTP API, allowing both humans and computers to discover and understand the service's capabilities without accessing source code, documentation, or inspecting network traffic

Format: YAML - human-readable data serialization language - with a hierarchical collection of properties and values that describe a REST API

Purpose: used to create both the interface and documentation, but, the OAS document itself is neither implementation nor documentation - it requires interpretation before it can become either

Document structure:

Section	Purpose
`info`	Metadata about the specification document
`servers`	List of servers that support the API
`tags`	Tokens used to group and organize endpoints such as resource names
`security`	Security schemes used to restrict API access
`paths`	URL path segments and their operations
`components`	Reusable objects referenced throughout the document

Path properties:

Property	Description
`summary`	Short description; appears as the API operation name
`description`	Detailed explanation of the API and how to use it
`tags`	Groups similar paths together
`operationId`	Unique identifier for this operation
`parameters`	URL and query parameters - URL parameters appear in the path itself
`responses`	All possible HTTP responses for requests to this path

Related terms: API, API reference topic, reference, REST API, schema

Sources:

UW API Docs: Module 5, Lesson 2, "Open API specification (OAS) documents"
Wikipedia: YAML

quickstart

Definition: condensed documentation that provides the absolute least amount of steps needed to achieve first success with a product; prioritizes speed over comprehensiveness

Purpose: enables immediate hands-on experience and demonstrates value within minutes; hooks developers quickly before they explore deeper documentation

Key Characteristics:

concise - often a tenth the length of full documentation
action-oriented with minimal explanation
shows one clear path to success
may use simplified examples or defaults
targets developers who want fast results
single page or short video format

Example: a quickstart for a payment API provides a pre-configured code snippet that processes a test transaction in three steps: copy the code, add an API key, run the script - achievable in under five minutes

Related Terms: getting started, how-to guide, introduction, task, tutorial

Sources:

reference

Definition: documentation topic type; provides detailed, factual information about APIs, commands, parameters, or system specifications; designed for lookup rather than learning

Purpose: serves as a comprehensive source of technical details that developers consult during implementation; prioritizes completeness and accuracy over explanation

Key Characteristics:

structured, consistent format
lists all available options, parameters, or endpoints
includes data types, default values, and constraints
minimal explanatory text
optimized for scanning and searching

Example: an API reference lists all endpoints with their HTTP methods, parameters, request/response formats, and status codes

Source: GitLab Docs: "Reference topic type"

runbook

Definition: documentation topic type; step-by-step team guide for completing common tasks or procedures; provides standardized instructions for operational or maintenance activities

Purpose: ensures consistency and reliability when executing routine or critical procedures; enables any team member to perform necessary tasks correctly

Key Characteristics:

procedural instructions for specific operations
designed for scanning for specific steps or in sequence
often includes context about when and why to use the procedure
targets team members at many experience levels
critical for incident response and routine maintenance

Example: a deployment runbook details the exact steps to deploy code to production, including pre-deployment checks, deployment commands, verification steps, and rollback procedures

Related Terms: how-to guide, onboarding guide, task, troubleshooting

Source: Squarespace Engineering: "Part 1: Learn The Different Types Of Technical Documentation"

task

Definition: documentation topic type; guides users through completing a specific goal; focuses on "how to" perform an action with step-by-step instructions

Purpose: enables users to complete work efficiently without needing to understand all underlying concepts

Key Characteristics:

starts with a clear goal
provides numbered steps in logical order
includes prerequisites when necessary
may include expected results or verification steps
focuses on one specific outcome

Example: a task topic titled "Authenticate with OAuth 2.0" lists the exact steps to configure OAuth credentials and enable the authentication flow

Related Terms: concept, getting started, quickstart, reference, runbook, troubleshooting, tutorial

Source: GitLab Docs: "Task topic type"

top-level

Definition: documentation topic type; high-level page that introduces a subject area and provides navigation to related topics; serves as an entry point for a documentation section

Purpose: orients readers to available resources, establishes information architecture, and helps users find relevant documentation quickly

Key Characteristics:

broad overview of the subject area
links to child topics organized logically
minimal detailed content
may include brief descriptions of linked topics
focuses on navigation and discoverability

Example: a "Security" top-level page introduces security concepts and links to topics about authentication, authorization, encryption, and security best practices

Related Terms: API overview topic, concept, getting started, introduction

Source: GitLab Docs: "Top-level page type"

troubleshooting

Definition: documentation topic type; helps users diagnose and resolve specific problems or error conditions; structured around symptoms, causes, and solutions

Purpose: enables users to fix issues independently by providing targeted guidance for common problems; reduces support burden and improves user experience

Key Characteristics:

describes the problem or error condition
lists possible causes
provides step-by-step solutions
may include diagnostic steps to identify the issue
often organized by error message or symptom

Example: a troubleshooting topic for API errors explains common HTTP status codes like 401 Unauthorized and 429 Too Many Requests, describes why they occur, and provides steps to resolve them

Related Terms: concept, error handling, HTTP status codes, runbook, task

Source: GitLab Docs: "Troubleshooting topic type"

tutorial

Definition: documentation topic type; guides users through a complete, real-world scenario from start to finish; combines many tasks and concepts into a cohesive learning experience

Purpose: teaches users how to apply a product or feature to solve a practical problem; builds skills and confidence through hands-on practice with a meaningful outcome

Key Characteristics:

focuses on a realistic use case or scenario
includes many steps or stages
combines tasks with conceptual explanations
takes longer to complete than a single task
often includes a working example or project as the result

Example: a tutorial titled "Build a REST API client" walks through setting up a development environment, authenticating with an API, making requests, handling responses, and implementing error handling

Related Terms: concept, getting started, how-to guide, onboarding guide, quickstart, task

Source: GitLab Docs: "Tutorial page type"

API Fundamentals​

API​

API endpoint​

API security​

authentication​

authorization​

CRUD​

DELETE​

error handling​

GET​

HTTP​

HTTP method​

HTTPS​

HTTP status codes​

HTTP versions​

idempotent​

JSON​

parameters​

payload​

PATCH​

POST​

PUT​

rate limiting​

request/response​

resource​

schema​

serialization​

URI​

URL​

validation​

Documentation-specific Concepts​

API overview topic​

API reference topic​

concept​

explanation guide​

getting started​

glossary​

how-to guide​

introduction​

onboarding guide​

OpenAPI Specification​

quickstart​

reference​

runbook​

task​

top-level​

troubleshooting​

tutorial​

API Fundamentals

API

API endpoint

API security

authentication

authorization

CRUD

`DELETE`

error handling

`GET`

HTTP

HTTP method

HTTPS

HTTP status codes

HTTP versions

idempotent

JSON

parameters

payload

`PATCH`

`POST`

`PUT`

rate limiting

request/response

resource

schema

serialization

URI

URL

validation

Documentation-specific Concepts

API overview topic

API reference topic

concept

explanation guide

getting started

glossary

how-to guide

introduction

onboarding guide

OpenAPI Specification

quickstart

reference

runbook

task

top-level

troubleshooting

tutorial