Api Documentation Examples

Standard Operating Procedure: api documentation examples

1. Document Control & Revision History

---

2. Executive Summary & Scope

2.1 Purpose

This Standard Operating Procedure (SOP) establishes the mandatory, repeatable framework for authoring, validating, testing, and maintaining Application Programming Interface (API) documentation examples across all enterprise tiers. Accurate, reproducible examples are critical operational assets that mitigate integration friction, prevent catastrophic runtime consumption errors, and maintain strict adherence to enterprise architecture standards.

2.2 Operational Boundaries

This procedure applies universally to all internal, partner-facing, and public RESTful, GraphQL, and gRPC APIs developed, maintained, or integrated by enterprise engineering squads. It governs documentation assets residing in source control repositories, developer portals (e.g., Backstage, ReadMe, Redocly), and automated testing pipelines.

2.3 Regulatory & Compliance Standards

All API documentation examples must comply with the following institutional mandates:

• OWASP API Security Top 10: Prevention of credential exposure, verbose error leaking, and mass assignment vectors in request/response payloads.
• GDPR/CCPA/HIPAA: Complete anonymization and synthetic masking of Personally Identifiable Information (PII), Protected Health Information (PHI), and financial account structures within mock payloads.
• OpenAPI Specification (OAS) 3.1.0: Strict adherence to structural typing, schema validation, and semantic versioning.

---

3. Prerequisites & Tool Requirements

Execution of this SOP requires specific hardware, software entitlements, and operational clearances. Uncertified personnel are strictly prohibited from modifying production-bound documentation gates.

3.1 Software & Toolchain Access

• Source Control Management (SCM): Enterprise GitHub Enterprise or GitLab Ultimate instance with write access to the targeted service repository.
• Documentation Linters & Validators:
  • Spectral (v6.x or higher) with custom enterprise ruleset (.spectral.yaml).
  • Redocly CLI for bundle validation and HTML rendering.
• API Testing Clients: Postman Enterprise (with automated collection runner) or Insomnia Enterprise, paired with Newman for CLI-driven contract testing.
• CI/CD Pipeline Engine: GitHub Actions or GitLab CI runner configured with API documentation validation workflows.

3.2 Credentials & Security Clearances

• RBAC Permissions: Least-privilege access token mapped to the API documentation repository with Actions workflow trigger privileges.
• Synthetic Test Environment Credentials: Read/Write access to the staging API sandbox environment populated with synthetic datasets only.

---

4. Roles & Responsibilities (RACI Matrix Table)

• Responsible (R): The role that performs the activity and authors the examples.
• Accountable (A): The role with final approval authority and operational accountability.
• Consulted (C): Subject matter experts providing input on security, architecture, or consumption patterns.
• Informed (I): Stakeholders kept updated on status and deployments.

---

5. Step-by-Step Operational Procedure

Phase 1: Payload Structuring & Synthetic Data Generation

• 1.1 Extract the definitive data models directly from the source code schema definitions (e.g., Pydantic, TypeScript interfaces, or JSON Schema).
• 1.2 Replace all production variables with realistic, deterministic synthetic data conforming to RFC standards (e.g., uuidv4, ISO-8601 timestamps, mock RFC 5322 emails).
• 1.3 Verify that no real PII, internal IP addresses, production database IDs, or secret keys exist within the draft examples.
• 1.4 Construct both success (HTTP 2xx) and failure/error (HTTP 4xx, 5xx) example payloads, ensuring exact parity with the service's serialization logic.

Phase 2: Specification Integration & Formatting

• 2.1 Embed the generated examples directly into the OpenAPI 3.1 specification file under the corresponding paths.<path>.<method>.responses.<status_code>.content.<media_type>.examples object.
• 2.2 Ensure every example includes a clear summary and description string explaining the functional state it represents (e.g., "Successful account creation with multi-factor authentication enabled").
• 2.3 Utilize external referencing ($ref) where payload duplication occurs across multiple endpoints, preserving DRY (Don't Repeat Yourself) principles.

Phase 3: Automated Validation & Contract Testing

• 3.1 Execute the local Spectral linting command to verify specification integrity: spectral lint api/openapi.yaml --ruleset .spectral.yaml
• 3.2 Confirm zero errors and zero warnings are returned by the linter before proceeding.
• 3.3 Execute contract tests via Newman to verify that the mock examples successfully validate against the live staging API endpoints: newman run tests/api-contract-collection.json -e tests/staging-environment.json

Phase 4: Peer Review & Compliance Sign-Off

• 4.1 Open a formal Pull Request (PR) in the SCM pointing to the main or release branch, utilizing the standardized enterprise API PR template.
• 4.2 Assign the PR to the API Product Owner for operational review and the Security Auditor if authentication headers or risk profiles changed.
• 4.3 Resolve all inline comments and automated CI pipeline checks generated by the documentation build bot.
• 4.4 Merge the branch upon receiving formal electronic sign-off from the Accountable role.

---

6. Quality Assurance & Verification Criteria

To clear the production release gate, API documentation examples must satisfy the following strict quantitative and qualitative benchmarks:

• Linter Compliance: 100% adherence to enterprise Spectral rulesets; zero tolerance for syntax, indentation, or schema mismatch warnings.
• Schema Parity: Automated JSON schema validation checking must demonstrate a 100% match rate between the documented example payload and the actual runtime JSON response emitted by the staging service.
• Completeness Index: Every documented endpoint must contain at minimum:
  • One successful execution example (200 OK or 201 Created).
  • One standard client-side error example (400 Bad Request or 422 Unprocessable Entity).
  • One standard authorization/authentication error example (401 Unauthorized or 403 Forbidden).
• Latency & Portability: Documentation portals must successfully build and render within 120 seconds of push events without asset resolution failures.

---

7. Practical Troubleshooting Scenarios

Scenario A: Spectral Linter Fails Due to Type Mismatch on Integer/String Field

• Symptom: CI pipeline fails at Phase 3 with error: oapilint-schema-type: property 'id' expected type 'integer', received 'string' in example object.
• Root Cause: The OpenAPI schema defines the unique identifier as an integer (type: integer, format: int64), but the author provided a quoted string (e.g., "id": "104928") in the documentation example block.
• Immediate Corrective Action Protocol:
  1. Locate the offending example within the OpenAPI spec file using the line number provided in the CI error log.
  2. Remove the quotation marks surrounding the numeric value to match the integer schema definition.
  3. Re-run local Spectral validation (spectral lint).
  4. Commit and push the corrected schema file to trigger a fresh CI verification run.

Scenario B: Automated Contract Test Fails Due to Missing Required Field in Payload

• Symptom: Newman contract test suite fails with: AssertionError: response body does not match schema: missing required property 'updated_at'.
• Root Cause: The underlying API codebase was updated to require a new timestamp field in the response payload, but the documentation example was not updated concurrently.
• Immediate Corrective Action Protocol:
  1. Identify the missing field from the schema definition file (openapi.yaml).
  2. Generate an appropriate ISO-8601 mock timestamp string (e.g., 2026-03-30T14:22:10Z).
  3. Insert the missing property into the relevant response example object.
  4. Execute the local Newman integration test suite to verify full contract alignment.
  5. Submit an expedited hotfix PR referencing this SOP failure protocol.