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.