API Reference Documentation — Complete Guide

API reference documentation provides complete, accurate endpoint descriptions required for integration. Learn how to structure API references using OpenAPI, write clear parameter descriptions, and document request and response examples.

What You'll Learn

You will learn how to create comprehensive API reference documentation using OpenAPI specifications, how to describe endpoints clearly, and how to ensure accuracy through testing.

Why It Matters

API reference documentation is the most consulted content in a developer portal. Incomplete or inaccurate references cause integration failures, support tickets, and developer frustration.

Real-World Use

The Durga Antivirus Pro threat intelligence API uses OpenAPI 3.0 for its reference documentation. Every endpoint includes request parameters, response schemas, authentication requirements, and code examples in Python and curl.

flowchart LR
  A[OpenAPI Spec] --> B[Endpoint Documentation]
  B --> C[Request Parameters]
  B --> D[Response Schemas]
  B --> E[Authentication]
  B --> F[Code Examples]
  C --> G[Try It Playground]
  F --> H[curl]
  F --> I[Python]
  F --> J[JavaScript]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

OpenAPI Endpoint Structure

openapi: 3.0.3
info:
  title: Durga Threat Intelligence API
  version: 1.3.0
  description: "REST API for accessing real-time threat data from
    Durga Antivirus Pro. Query threat signatures, get IoC feeds,
    and submit samples for analysis."
paths:
  /threats:
    get:
      summary: List recent threats
      description: "Returns a paginated list of recently detected
        threats. Results are ordered by detection timestamp
        descending."
      operationId: listThreats
      parameters:
        - name: limit
          in: query
          description: "Maximum number of threats to return.
            Default: 20. Maximum: 100."
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: severity
          in: query
          description: "Filter by threat severity level.
            Multiple values can be comma-separated."
          schema:
            type: string
            enum: [low, medium, high, critical]
      responses:
        '200':
          description: A paginated list of threats
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Threat'
                  total:
                    type: integer
                  page:
                    type: integer
      security:
        - apiKey: []

Code Examples in Each Language

# curl example
curl -X GET "https://api.durgaantivirus.com/v1/threats?limit=20&severity=critical" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Python example
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.durgaantivirus.com/v1"

response = requests.get(
    f"{BASE_URL}/threats",
    params={"limit": 20, "severity": "critical"},
    headers={"Authorization": f"Bearer {API_KEY}"}
)
print(response.json())

// JavaScript example
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.durgaantivirus.com/v1";

const response = await fetch(`${BASE_URL}/threats?limit=20&severity=critical`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`
  }
});
const data = await response.json();
console.log(data);

Response Documentation

components:
  schemas:
    Threat:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier for the threat"
        name:
          type: string
          description: "Threat name as identified by detection engine"
        severity:
          type: string
          enum: [low, medium, high, critical]
        detected_at:
          type: string
          format: date-time
          description: "ISO 8601 timestamp of detection"
        status:
          type: string
          enum: [active, quarantined, resolved]

Common Mistakes

1. Describing What, Not Why

Parameter descriptions should explain the purpose, not just repeat the name. "Maximum number of threats to return" is better than "Limit parameter."

2. No Default Values

Missing default values force developers to guess. Always specify defaults, minimums, and maximums.

3. Inconsistent Response Formats

Different endpoints returning different response structures confuse developers. Use consistent response patterns.

4. No Error Response Documentation

Developers spend significant time handling errors. Document every error code, its meaning, and how to resolve it.

5. Outdated Code Examples

Code examples that use deprecated syntax or wrong parameter names cause integration failures. Test every example.

Practice Questions

1. What information should every endpoint description include?

Summary, description, request parameters (with defaults), response schemas, error codes, authentication requirements, and code examples.

2. Why should parameter descriptions explain purpose, not just repeat the name?

"Limit parameter" tells developers nothing. "Maximum number of threats to return" tells them what the parameter does.

3. How many code example languages should an API reference include?

At least three: curl for quick testing, plus the two most popular languages for your developer audience.

4. Why is error response documentation important?

Developers encounter errors during integration. Documented error codes with resolution steps reduce debugging time.

5. Challenge: Write an OpenAPI 3.0 specification for a simple API endpoint. Include path and query parameters, request body, response schema, authentication, and error responses. Verify it renders correctly in Swagger UI or Redoc.

FAQ

Mini Project

Write an OpenAPI 3.0 specification for three endpoints of a sample API (list, get, create). Include authentication, request parameters, response schemas, error codes, and code examples in curl and Python. Render with Redoc and verify accuracy.

What's Next

After API reference, learn how to write Getting Started Guides that get developers to their first successful API call in under 5 minutes.