Ship Developer-Friendly API Reference: Templates, Examples, and CI for Freelancers

An API reference is where developer trust is won or lost. As a freelance technical writer, your job is to make the surface-level experience clear and the deep-dive precise. This article gives a repeatable template, sample endpoint entry, code snippets in Node and Python, and a docs-as-code CI workflow to keep examples accurate.

Audience

• Developers integrating with the API (first-timers and maintainers)
• Engineering stakeholders who need reproducible examples

Reference structure (standard sections)

• Overview: Purpose, base URL, authentication
• Quickstart: 5-minute path to first response
• Authentication: tokens, scopes, rotation
• Rate limits & quotas
• API Reference: endpoints organized by resource
• SDK samples: idiomatic examples for common languages
• Errors & troubleshooting
• Changelog & migration guide

API endpoint template (copy this into your docs)

<h3>GET /v1/items/{item_id}</h3>
<p>Summary: Retrieve a single item by ID</p>
<h4>Path parameters</h4>
<ul>
  <li>item_id (string, required) — Unique ID of the item</li>
</ul>
<h4>Query parameters</h4>
<ul>
  <li>expand (string, optional) — Comma-separated relations to expand</li>
</ul>
<h4>Request example (curl)</h4>
<pre><code>curl -H 'Authorization: Bearer $API_KEY' \
  'https://api.example.com/v1/items/itm_123?expand=owner'</code></pre>
<h4>Success (200)</h4>
<pre><code>{
  "id": "itm_123",
  "name": "Colors",
  "owner": {"id": "u_1", "name": "Alex"}
}
</code></pre>
<h4>Errors</h4>
<ul>
  <li>401 Unauthorized — Invalid API key</li>
  <li>404 Not Found — item_id does not exist</li>
</ul>

Example endpoint: full entry

Below is a worked example with schema and error table.

GET /v1/projects/{project_id}/deploys
Summary: List deployments for a project
Path parameters:
  - project_id (string, required)
Query parameters:
  - status (string, optional) — one of: pending, running, succeeded, failed
  - limit (integer, optional) — default 20
Request example (curl):
  curl -H 'Authorization: Bearer $API_KEY' \
       'https://api.example.com/v1/projects/abc123/deploys?status=succeeded&limit=10'
Success (200):
  {
    "deploys": [
      {"id": "dpl_1", "status": "succeeded", "created_at": "2025-01-01T12:00:00Z"}
    ],
    "limit": 10
  }
Errors:
  401 — Unauthorized: Invalid or missing API key
  404 — Not Found: project_id not found
  429 — Too Many Requests: rate limit exceeded

Idiomatic snippets

Node (axios)

const axios = require('axios')
async function listDeploys(projectId, status) {
  const res = await axios.get(`https://api.example.com/v1/projects/${projectId}/deploys`, {
    params: { status, limit: 10 },
    headers: { Authorization: `Bearer ${process.env.API_KEY}` }
  })
  return res.data
}

Python (requests)

import os
import requests

def list_deploys(project_id, status=None):
    params = {k: v for k, v in (("status", status), ("limit", 10)) if v is not None}
    resp = requests.get(
        f'https://api.example.com/v1/projects/{project_id}/deploys',
        headers={'Authorization': f'Bearer {os.getenv("API_KEY")}'},
        params=params,
    )
    resp.raise_for_status()
    return resp.json()

Error codes and handling table (recommended format)

HTTP  Code  | Name         | Description / Action
-----------+--------------+---------------------------------
401        | Unauthorized | Check API key, check scopes
403        | Forbidden    | Permission error — contact admin
404        | Not Found    | Check resource id
422        | Invalid      | Validation failed — inspect body
429        | Too Many Req | Backoff and retry later
500        | Server Error | Contact support, include request-id

Docs-as-code CI checklist

• Lint Markdown (markdownlint) and enforce rule set.
• Validate OpenAPI spec (spectral or openapi-validator).
• Run snippet tests: execute curl/postman requests against staging or mocked server.
• Schema checks: compare response shapes to JSON schema and fail on mismatch.
• Accessibility checks: run axe for pages with UI previews.

Simple CI pipeline (GitHub Actions outline)

name: Docs CI
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run markdownlint
        run: npx markdownlint-cli '**/*.md'
  validate-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Validate OpenAPI
        run: npx @stoplight/spectral lint api/openapi.yaml
  snippet-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Postman collection
        run: newman run collections/docs-examples.postman_collection.json --env-var "baseUrl=https://staging.api.example.com" --env-var "apiKey=${{ secrets.STAGING_API_KEY }}"

Documentation style checklist

• Voice: Present tense, second person for tasks; third person for reference sentences.
• Code formatting: Language tags, minimal line length, show both request and response.
• Naming: Use consistent resource case (camelCase for JSON fields or snake_case — pick one).
• Versioning: Embed API version in URL and include migration notes for major versions.
• Changelog: Use a single changelog file with semantic grouping and links to PRs.
• Localization: Keep strings short, avoid idioms; mark translatable text; separate images with embedded text.

Client deliverables and time estimates

• API reference template & one fully documented resource: 2–4 days.
• Full reference (20–50 endpoints): 2–4 weeks depending on complexity.
• CI integration for snippet validation: 1–3 days.
• Post-launch maintenance retainer: recommended (4–8 hours/month).

Proposal snippet (ready to send)

Scope: Produce API reference for v1 (20 endpoints), include Node & Python snippets, integrate OpenAPI validation and snippet tests in CI.
Duration: 3 weeks
Cost: $X (fixed)
Deliverables:
  - Complete API reference in Markdown
  - OpenAPI validation in CI
  - Postman collection + snippet test harness
  - Handover and maintenance plan

Handover checklist

• Credentials (staging and prod) and example data.
• OpenAPI/Swagger file and schema ownership.
• Engineer reviewer + sign-off process.
• CI secrets for snippet tests stored in repo secrets.
• Access to docs hosting or Git repo for publishing.

Tools recommended

• Docs site: Docusaurus, MkDocs, or Hugo
• API-first: OpenAPI, Redoc, Stoplight
• Snippet testing: Postman/Newman, pytest + requests, or custom test harness
• CI: GitHub Actions, GitLab CI
• Linting: markdownlint, spectral

Final tips for accuracy and reproducibility

• Keep examples minimal and executable — a developer should be able to copy, paste, and run.
• Prefer generated or tested examples over handwritten ones.
• Automate as many checks as possible in CI so docs drift is caught early.
• Maintain simple smoke tests that run on every PR and post-merge.

Use this article as a template for proposals, reference pages, and CI pipelines. When in doubt, prefer verifying over guessing — reproducible examples build trust faster than perfect prose.