Technical Writing and Documentation 101: API Reference Documentation (Endpoints, Parameters, Responses, Code Samples)

API Reference Documentation (Endpoints, Parameters, Responses, Code Samples)

API Reference Documentation: A Portfolio-Ready Study Guide

For aspiring technical writers, developers transitioning into writing, and current writers modernizing their skills

What This Is

API reference documentation is the detailed, structured manual for developers using an API. It lists every endpoint (e.g., GET /users), describes parameters (e.g., ?limit=10), explains responses (e.g., 200 OK with a JSON payload), and provides runnable code samples (e.g., curl, Python, JavaScript). Without clear API docs, developers waste hours guessing how to integrate—imagine trying to use Stripe’s payment API without knowing which endpoint charges a credit card or what fields are required.

Real-world example:
Stripe’s API reference shows: - Endpoint: POST /v1/charges - Parameters: amount, currency, source - Response: 200 (success) or 402 (failed payment) - Code samples in 7 languages.

Key Terms & Tools

• OpenAPI (formerly Swagger):
  A machine-readable spec (YAML/JSON) that describes REST APIs. Tools like Swagger UI or ReDoc auto-generate interactive docs from it. Example: Petstore OpenAPI spec.

• Docs-as-Code:
  Treating docs like code—stored in Git, written in Markdown/AsciiDoc, built with static site generators (e.g., Sphinx, Docusaurus), and reviewed via pull requests.

• Endpoint:
  A URL path (e.g., /users/{id}) that performs an action (GET, POST, PUT, DELETE). Think of it as a "door" to a specific API feature.

• Parameters:
  Inputs passed to an endpoint (e.g., query params ?sort=asc, path params /users/{id}, headers Authorization: Bearer token, or request body JSON).

• Response Schema:
  The structure of the API’s output (e.g., {"id": "123", "name": "Alice"}). Defined in JSON Schema or OpenAPI.

• Code Samples:
  Snippets in languages like curl, Python, JavaScript, or Go that show exactly how to call the API. Example: bash curl -X POST https://api.example.com/users \
-H "Authorization: Bearer token" \
-d '{"name": "Alice"}'

• Status Codes:
  HTTP responses like 200 OK (success), 404 Not Found (missing resource), or 429 Too Many Requests (rate-limited). Always document these!

• Authentication:
  How users prove their identity (e.g., API keys, OAuth2, JWT). Example: Stripe uses Authorization: Bearer sk_test_....

• SDKs (Software Development Kits):
  Language-specific libraries (e.g., stripe-python) that wrap API calls. Docs should link to SDKs if they exist.

• Postman/Newman:
  Tools for testing APIs and auto-generating docs. Postman collections can export to OpenAPI.

• DITA (Darwin Information Typing Architecture):
  An XML-based standard for modular docs (used in enterprise). Less common for APIs but useful for reusable content (e.g., error message tables).

• Static Site Generators (SSGs):
  Tools like Docusaurus, MkDocs, or Sphinx that build fast, version-controlled docs from Markdown. Example: GitHub’s API docs use Docusaurus.

Step-by-Step / Process Flow

Follow this workflow to create accurate, usable API docs:

1. Read the API spec or code
2. Start with the OpenAPI spec (if it exists) or the API’s source code (e.g., routes/users.js in Node.js).

3. Talk to developers: "What are the most common use cases? What errors do users hit?"

4. Test the endpoint manually

5. Use Postman, curl, or httpie to call the API. Example:
   bash
curl -X GET https://api.example.com/users/1

6. Verify responses match the spec. If not, file a bug or update the docs.

7. Draft the resource description

8. Write a 1–2 sentence summary of the endpoint’s purpose. Example:
   > "Retrieves a user by ID. Returns 404 if the user doesn’t exist."

9. Use active voice and present tense (e.g., "Returns a user object" vs. "This endpoint will return...").

10. Document parameters and responses

11. Parameters: List name, type, required/optional, description, and example. Use a table or bullet points:
    | Parameter | Type | Required | Description | Example |
    |-----------|----------|----------|---------------------------|---------------|
    | id | string | Yes | User’s unique identifier | "abc123" |

12. Responses: Include status codes, schemas, and examples. Example:
    json
{
"id": "abc123",
"name": "Alice",
"email": "[email protected]"
}

13. Add code samples

14. Provide 3–5 languages (e.g., curl, Python, JavaScript, Java, Go). Example for Python:
    python
import requests
response = requests.get(
"https://api.example.com/users/1",
headers={"Authorization": "Bearer token"}
)
print(response.json())

15. Use realistic values (e.g., "abc123" instead of "id").

16. Submit for developer review

17. Open a pull request in Git with your changes. Ask developers:
    • "Does this match the current API behavior?"
    • "Are there edge cases I missed?"

18. Use GitHub/GitLab comments to discuss changes.

19. Automate (if possible)

20. Use OpenAPI + Swagger UI to auto-generate docs from the spec.
21. Set up CI/CD (e.g., GitHub Actions) to rebuild docs on every code push.

Common Mistakes

Tech Writing Interview / Portfolio Tips

What Hiring Managers Look For

1. Accuracy over polish

2. A well-tested but ugly API doc beats a beautiful but wrong one. Show you verify endpoints (e.g., screenshots of Postman tests in your portfolio).

3. Distinguishing reference vs. guides

4. Reference docs = "What does this endpoint do?" (e.g., GET /users).
5. Guides/tutorials = "How do I build X with this API?" (e.g., "How to Create a User").

6. Tricky distinction: A tutorial teaches concepts by building (e.g., "Build a Weather App with Our API"), while a how-to solves a specific problem (e.g., "How to Handle Rate Limits").

7. Tool proficiency

8. Know the difference between:
   • Swagger UI (interactive, auto-generated from OpenAPI).
   • ReDoc (prettier, but read-only).
   • Postman Docs (good for testing, but not a full doc site).

9. Example: "I used Docusaurus for the doc site and Swagger UI for interactive API exploration."

10. Portfolio projects

11. Mock an API doc for a fake service (e.g., "PetStore API") or improve an existing doc (e.g., fork GitHub’s API docs and add missing examples).
12. Include:
    • A README explaining your process (e.g., "I tested endpoints in Postman and added Python samples").
    • Before/after screenshots (e.g., "I rewrote the /orders endpoint to include error responses").

Quick Check Questions

1. A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?
2. Answer: Use OpenAPI specs + CI/CD to auto-generate docs on every code push. Example: GitHub Actions can rebuild docs when the main branch updates.

3. Why: Manual updates are error-prone; automation ensures accuracy.

4. You’re documenting a POST /orders endpoint. The API returns 201 Created on success but the spec says 200 OK. What do you do?

5. Answer: Test the endpoint—if it returns 201, update the docs to match. File a bug if the spec is wrong.

6. Why: The code’s behavior is the source of truth, not the spec.

7. A junior writer asks: "Should I document every possible error response?" How do you respond?

8. Answer: Document common errors (e.g., 401 Unauthorized, 422 Validation Failed) and link to a full list if the API has many edge cases.
9. Why: Over-documenting clutters the page; focus on what users need to debug.

Last-Minute Cram Sheet

1. OpenAPI 3.0 vs. 2.0: 3.0 uses components/schemas; 2.0 uses definitions.
2. Markdown tables: Use |---|---| for headers. Example:
   markdown
| Param | Type | Required |
|-------|--------|----------|
| id | string | Yes |
3. ⚠️ Never use "should" in docs—it’s ambiguous. Use "must" (required) or "can" (optional).
4. Status codes to always document: 200, 201, 400, 401, 403, 404, 429, 500.
5. Code sample best practices:
6. Use realistic values (e.g., "abc123" not "id").
7. Include error handling (e.g., try/catch in Python).
8. Swagger UI vs. ReDoc: Swagger UI is interactive (try endpoints live); ReDoc is prettier but read-only.
9. ⚠️ A tutorial is not a how-to guide—tutorials teach concepts by building; how-tos solve specific problems.
10. Postman tip: Use environments to switch between dev/staging/prod URLs.
11. Docusaurus shortcut: npm run start to preview docs locally.
12. ⚠️ Avoid "etc." in docs—list all possible values (e.g., "status: active | inactive | pending").