API Spec & Documentation Writing Exercises
Learn vocabulary for writing OpenAPI specifications: field descriptions, error response documentation, and API changelog writing.
Frequently Asked Questions
What is the standard language for describing an OpenAPI endpoint?
An OpenAPI endpoint description should be concise, imperative, and developer-facing. The summary field uses a short verb phrase such as "Retrieve a paginated list of orders" or "Update user profile settings." The description field expands on behaviour, constraints, and side effects: "Returns orders filtered by status and date range. Results are sorted by creation date descending. Requires the orders:read scope." Avoid passive voice and implementation details that are irrelevant to the consumer.
How do you write clear parameter descriptions in an OpenAPI spec?
Parameter descriptions should state the purpose, accepted values, format, and any constraints. For example: "The ISO 8601 date from which to filter results (inclusive). Must not be in the future." or "The unique identifier of the resource. Must be a valid UUID v4." Always specify whether the parameter is required or optional, and document the default value if one exists. For enum parameters, list all accepted values with a brief explanation of each.
What vocabulary is used to document error responses in an API spec?
Error response documentation should name the error code, describe the condition that triggers it, and guide the consumer on how to recover. Standard phrasing: "Returned when the request body is missing a required field. Check the errors array for field-level validation details." or "Returned when the authenticated user does not have permission to access this resource. Ensure the token includes the required scope." Always document the response body schema alongside the HTTP status code.
How do you write a good API changelog entry?
A changelog entry should clearly categorise the change (Added, Changed, Deprecated, Removed, Fixed, Security), identify the affected endpoint or schema, and explain the impact on consumers. Example: "Changed — GET /users now returns a cursor-based pagination object instead of offset/limit fields. Clients must update their pagination logic. See the migration guide for details." Use semantic versioning to signal the severity of the change and always include the release date.
What is the correct terminology for describing authentication in an OpenAPI spec?
OpenAPI uses security scheme objects. Common documentation language: "This endpoint requires Bearer token authentication. Include the token in the Authorization header: Authorization: Bearer {token}." For OAuth 2.0 flows, document each scope: "Requires the profile:read scope. Request this scope during the authorisation code flow." The securitySchemes component should reference an external link to the full authentication guide for complex schemes.
How do you describe a "deprecated" field or endpoint in an API spec?
Mark the field or operation with the deprecated: true flag and add a description explaining the replacement and timeline: "Deprecated as of version 2.3. Use the tags array on the parent resource instead. This field will be removed in version 3.0, scheduled for Q3 2025." In changelogs, use the Deprecated section header. Always give consumers a reasonable migration window and a concrete replacement before removal.
What language conventions apply to request body schema descriptions?
Schema property descriptions should be written in third person and describe what the field represents, not how it is implemented. Example: "The customer's preferred display name. Maximum 100 characters. Supports Unicode. If omitted, defaults to the email address local part." For nested objects, describe the relationship: "An array of line items included in the order. At least one item is required." Consistent use of terms like "must," "should," and "may" (following RFC 2119 conventions) improves precision.
How do you communicate a rate limit policy in API documentation?
Rate limit documentation should state the limit, the window, the scope (per user, per IP, per API key), and the recovery mechanism. Standard phrasing: "Requests are limited to 1,000 per hour per API key. When the limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating when the limit resets." Document the rate-limit response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) so clients can implement back-off strategies.
What is the preferred style for writing example values in an OpenAPI spec?
Examples should be realistic, not placeholder text. Use domain-accurate sample data: real-looking UUIDs, valid ISO dates, plausible names, and correct enum values. Avoid "string," "foo," or "test123." OpenAPI supports both the example keyword (single value) and the examples keyword (named, multiple). A well-named example ("active_subscription" vs. "cancelled_subscription") helps developers understand distinct scenarios at a glance.
How do you document a webhook payload in an OpenAPI or AsyncAPI spec?
Webhook payloads are documented under the webhooks object in OpenAPI 3.1 or as channels in AsyncAPI. Describe the triggering event clearly: "Sent when an order transitions to the shipped state. The payload includes the full order object with tracking information populated." Document retry behaviour, expected response codes (typically 200 or 204), and signature verification if applicable: "Verify the X-Signature-256 header using your webhook secret to confirm the payload originated from our platform."