Skip to main content

API Fundamentals

Essential terms and concepts for understanding how APIs work. From HTTP methods and status codes, to authentication, data formats, and request-response patterns that apply across different API types, this section defines the foundational building blocks of API communication.


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

Essential API Descriptions:

  • 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 construct correct code
  • prevents developers from needing to reverse-engineer, which is often prohibited by license

Example API Request-Response Flow:

Related Terms: API documentation testing, API endpoint, API gateway, API security, CLI, 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:

PatternPurposeExample
/resourceCollection operationsGET /users lists all users
/resource/{id}Single resource operationsGET /users/123 retrieves one user
/resource/{id}/subresourceRelated resourcesGET /users/123/orders

Related Terms: API, API documentation testing, 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, Bruno, environment variables, 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 OperationHTTP MethodActionExample
CreatePOSTAdd new resourcePOST /users creates a new user
ReadGETRetrieve resourceGET /users/123 retrieves user 123
UpdatePUT or PATCHChange resourcePUT /users/123 edits entire user record
DeleteDELETERemove resourceDELETE /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:


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"


environment variables

Definition: dynamic values stored outside app code that configure program behavior across different deployment environments

Purpose: enables secure configuration management without hardcoding sensitive values; allows same codebase to work across development, staging, and production environments; often store configuration details, allowing tests to run in different environments without code changes

Example: API base URLs, authentication tokens, and database credentials stored as environment variables rather than committed to version control

Related Terms: API, API documentation testing, API security, authentication, Bruno

Source: Silva, Manny. Docs As Tests. First edition, Release 2, Boffin Education, May 2025.


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

Related Terms: API endpoint, AsyncAPI, error-handling, HTTPS, HTTP status codes, HTTP versions, REST API

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 RangeCategoryMeaning
1xxInformationalRequest received, continuing process
2xxSuccessRequest successfully received, understood, and accepted
3xxRedirectionFurther action needed to complete the request
4xxClient ErrorRequest contains bad syntax and/or server can't process
5xxServer ErrorServer failed to fulfill an apparently valid request

Common Status Codes:

CodeLabelMeaning
200OKRequest succeeded
201CreatedNew resource successfully created
204No ContentRequest succeeded but no content to return
400Bad RequestServer can't process due to client error
401UnauthorizedAuthentication required or failed
403ForbiddenServer understood but refuses to process
404Not FoundRequested resource doesn't exist
500Internal Server ErrorServer encountered an unexpected condition
503Service UnavailableServer 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"
}

Related Terms: API documentation testing, API endpoint, HTTP, rate limiting, request-response, REST API, troubleshooting, validation

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:

MethodIdempotentReason
DELETEYesDeleting an already-deleted resource has same outcome
GETYesReading data doesn’t change server state
PATCHDependsPartial updates may or may not be idempotent based on implementation
POSTNoCreating resources many times produces different results
PUTYesReplacing 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 CaseExample
Request bodySending data in POST or PUT requests
Response bodyReturning data from API endpoints
ConfigurationStoring API settings and options
Error messagesStructured error information

Related Terms: JSON-RPC, payload, REST API, serialization, XML, YAML

Source: JSON.org: "Introducing JSON"


message broker

Definition: intermediary software component that receives, stores, routes, and delivers messages between applications, services, or systems using messaging protocols

Purpose: enables asynchronous communication patterns where senders and receivers don't need to interact with messages simultaneously; decouples app components, improves scalability, and provides message persistence and delivery guarantees; essential for event-driven architectures and real-time data processing

Publish-Subscribe Pattern: message brokers commonly use publish-subscribe messaging where publishers send messages to topics without knowing who'll receive them, and subscribers receive messages from topics they're interested in without knowing who sent them; this decoupling allows independent scaling and evolution of system components

Example: e-commerce order processing with message broker

ComponentActionBenefit
Web appPublishes order message to brokerResponds to customer immediately
Inventory systemSubscribes to order messagesUpdates stock independently
Payment systemSubscribes to order messagesProcesses payment asynchronously
Shipping systemSubscribes to order messagesArranges delivery in parallel

Related Terms: AMQP, API, AsyncAPI, event-driven, Kafka, MQTT

Sources:


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:

TypeLocationPurposeExample
Path parametersIn the URL pathIdentify specific resources/users/{id}
Query parametersAfter ? in URLFilter, sort, or paginate results/users?role=admin&limit=10
Header parametersHTTP headersAuthentication, content typeAuthorization: Bearer token123
Body parametersRequest bodyComplex data for POST/PUTJSON 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

Break 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:

FormatUse CaseExample
JSONMost REST APIs{"name": "value"}
XMLLegacy systems, SOAP<name>value</name>
Form dataFile uploads, form submissionsname=value&email=user@example.com
BinaryFile transfers, imagesRaw bytes

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

Sources:


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:

PatternDescriptionExample
Fixed windowSet number of requests per time unit1000 requests per hour
Sliding windowRolling time window for more precision1000 requests per 60-minute window
Token bucketRequests consume tokens that regenerate10 tokens/second, burst up to 100
Per-userLimits apply to individual users/keys100 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

Related Terms: API security, authentication, authorization, error handling, HTTP status codes, validation

Sources:


request-response

Definition: 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:

ComponentDescriptionExample
HTTP methodAction to performGET, POST, PUT, DELETE
Endpoint URLResource locationhttps://api.example.com/users
HeadersMetadata about the requestContent-Type: application/json
BodyData sent with request - POST/PUTJSON object
ParametersRequest specificationsQuery or path parameters

Response Components:

ComponentDescriptionExample
Status codeOutcome of the request200, 404, 500
HeadersMetadata about the responseContent-Type: application/json
BodyData returned from serverJSON 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"
}

Request-Response Cycle - Python, Postman, PostgreSQL

Request-Response Diagram

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:

TypeExampleTypical Operations
Collection/usersList all, create new
Individual/users/123Read, edit, delete one
Nested/users/123/ordersAccess related resources
Singleton/profileRead 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:


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

Related Terms: API, API endpoint, GraphQL API, OpenAPI specification, request-response, validation

Sources:


SDK

Definition: acronym for software development kit; a collection of tools, libraries, code samples, and documentation that enables developers to build applications using a specific platform, service, or API

Purpose: streamlines API integration by providing pre-written code that handles authentication, request formatting, error handling, and response parsing; allows developers to use APIs in their preferred programming language without writing low-level HTTP requests; reduces integration time and errors by abstracting API complexity into language-specific methods and classes

SDK vs client library

While often used interchangeably, an SDK technically includes more than just a client library, it bundles the library with documentation, code examples, CLI tools, and other development resources; in API documentation contexts, "SDK" and "client library" both refer to language-specific code for consuming APIs, with SDK being the more common modern term

Example: compare the developer experience between using cURL commands vs using a Python SDK; technical writers must document all SDK methods, parameters, usage examples, and any additional and/or underlying API reference documentation

# raw cURL approach
curl https://api.stripe.com/v1/charges \
-u sk_test_key: \
-H "Content-Type: application/x-www-form-urlencoded" \
-d amount=1000 \
-d currency=usd
# Python SDK approach
stripe.Charge.create(
amount=1000,
currency="usd"
)

Related Terms: API, cURL, developer portal, Fern, OpenAPI Specification, REST API, Speakeasy

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, YAML

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:

CategoryComponentExampleDescription
howschemahttps://protocol for accessing the resource
wherehostapi.example.comserver location
optionalport:443HTTPS default, directs traffic
whatendpoint/path/v1/users/123specific resource location
optionalquery parameters?include=ordersrequest 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 primarily 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: