API Reference vs Guide — Different Documentation Types Explained

In this tutorial, you will learn about API Reference vs Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

API reference documentation describes every endpoint, parameter, and schema exhaustively, while conceptual guides explain how to accomplish specific tasks and solve real problems using the API.

In this tutorial, you will learn the distinction between reference and guide documentation, when each is appropriate, and how to organize both into a cohesive developer documentation set.

What You'll Learn

You will learn the purpose and audience of reference docs versus guides, how to structure each type, what content belongs where, and how to cross-link them for maximum developer effectiveness.

Why It Matters

Many API documentation sets fail because they provide only reference without guides, or only tutorials without complete reference. Developers need both: reference to look up specifics and guides to learn how to use the API effectively.

Real-World Use

DodaTech developer portal separates content into three sections: API Reference (generated from OpenAPI), Getting Started Guides (tutorials for common tasks), and Integration Guides (deep dives into specific features like file uploads and Webhooks).

flowchart LR
  A[Developer Docs] --> B[API Reference]
  A --> C[Conceptual Guides]
  A --> D[Getting Started]
  B --> E[Endpoints]
  B --> F[Schemas]
  B --> G[Errors]
  C --> H[Tutorials]
  C --> I[Best Practices]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

API Reference Documentation

API reference documentation is exhaustive, structured, and generated from the OpenAPI spec. It answers the question: what does this endpoint do?

Characteristics of good reference documentation:

• Complete coverage of every endpoint
• Every parameter documented with type, format, and constraints
• Every response with status code, schema, and example
• Error codes for every failure mode
• Authentication requirements per endpoint
• Rate limit information

Reference docs are typically generated automatically from the OpenAPI specification. This ensures accuracy but requires the spec to be well-written.

# OpenAPI spec that generates good reference docs
paths:
  /users:
    get:
      summary: List all users
      description: |
        Returns a paginated list of users on the DodaTech platform.
        Results are sorted by creation date descending.
      parameters:
        - name: page
          in: query
          description: Page number for pagination (1-indexed)
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Items per page (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        "200":
          description: Paginated list of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/User"
                  pagination:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"

Conceptual Guides

Conceptual guides explain how to use the API to accomplish tasks. They answer the question: how do I solve this problem with this API?

Good guides include:

• A clear goal (what the reader will accomplish)
• Prerequisites and assumptions
• Step-by-step instructions
• Complete code examples (not just snippets)
• Expected output at each step
• Common pitfalls and how to avoid them
• Links to relevant reference documentation

# Guide: Bulk User Import

## Goal

Import 1000 users from a CSV file into the DodaTech platform.

## Prerequisites

- An API key with write:users scope
- A CSV file with columns: name, email, role
- Python 3.8+ with the requests library

## Step 1: Parse the CSV

```python
import csv
import requests

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

with open("users.csv", "r") as f:
    reader = csv.DictReader(f)
    users = list(reader)

print(f"Loaded {len(users)} users from CSV")
# Expected: Loaded 1000 users from CSV

Step 2: Import Users in Batches

BATCH_SIZE = 100

for i in range(0, len(users), BATCH_SIZE):
    batch = users[i : i + BATCH_SIZE]
    response = requests.post(
        f"{BASE_URL}/users/batch",
        headers={"X-API-Key": API_KEY},
        json={"users": batch}
    )

    if response.status_code == 201:
        print(f"Imported batch {i // BATCH_SIZE + 1}")
    else:
        print(f"Batch failed: {response.json()['message']}")

Step 3: Verify Import

response = requests.get(
    f"{BASE_URL}/users",
    headers={"X-API-Key": API_KEY},
    params={"limit": 1}
)
total = response.json()["pagination"]["total"]
print(f"Total users after import: {total}")
# Expected: Total users after import: [previous_count + 1000]

See the Users API Reference for endpoint details.

## Getting Started Guide

The getting started guide is the most important page in your documentation. It should take a developer from zero to a successful API call in under 5 minutes.

```markdown
# Getting Started with DodaTech API

This guide will help you make your first API call in 3 minutes.

## 1. Get Your API Key

Visit the Developer Dashboard and click Create API Key.

## 2. Make a Test Request

```bash
curl -X GET "https://api.dodatech.com/v1/health" \
  -H "X-API-Key: YOUR_API_KEY"

Expected response:

{"status": "ok", "version": "2.1.0"}

3. Next Steps

• Read the Authentication guide
• Explore the API Reference
• Try the User Management tutorial

## Organizing Documentation

A complete documentation set includes:

**Top level**: Getting Started (must read first), API Reference (for lookup), Guides (for learning), Changelog (for updates)

**API Reference section**: Grouped by resource (Users, Documents, Files). Each resource has endpoints, schemas, and errors.

**Guides section**: Task-based tutorials sorted by complexity. Beginner, Intermediate, Advanced.

## Common Mistakes

1. **Only providing reference documentation** — Listing endpoints without explaining how to use them. Developers need both reference and guides to be productive.

2. **Writing guides without reference links** — Showing code without linking to the actual endpoint documentation. Every code example should link to the relevant reference.

3. **Mixing reference and guides** — Putting tutorial content inside endpoint descriptions. Keep reference factual and exhaustive. Keep guides instructional and task-focused.

4. **No getting started guide** — Expecting developers to figure out the first call from reference docs. The getting started guide is the most important page.

5. **Inconsistent depth** — Some endpoints have detailed docs while others have one-line descriptions. Maintain consistent depth across all documentation.

## Practice Questions

1. What is the difference between API reference and conceptual guides?
2. What content belongs in an API reference page?
3. What content belongs in a conceptual guide?
4. Why is the getting started guide the most important documentation page?
5. How should you organize a complete documentation set?

## Challenge

Audit an existing API documentation set (choose a public API). Identify which pages are reference, which are guides, and which are missing. Write a proposal for restructuring the documentation with a clear separation of reference and guide content.

## FAQ

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">Can one page serve as both reference and guide?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>No. Reference and guides serve different purposes. Reference is for lookup. Guides are for learning. Mixing them creates pages that are neither comprehensive reference nor effective tutorials.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">How long should a getting started guide be?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Short enough to complete in 5 minutes. Three to five steps with code examples. Long guides should be separate tutorials referenced from the getting started page.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">Should I write guides before reference?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Write the getting started guide first. Then write the OpenAPI spec for reference. Then write task-based guides for common use cases.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">How do I handle advanced topics in guides?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Create separate guides for beginner, intermediate, and advanced topics. Label them clearly. Link between them for progressive learning.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">What is the ideal documentation-to-reference ratio?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>For a typical API, aim for one guide per 5-10 endpoints. Not every endpoint needs a guide, but every common workflow should have one.</p>
</div></details>

## Mini Project

Design the information architecture for a documentation set for a video streaming API. List the reference pages (endpoint groups, schemas) and guide pages (getting started, uploading videos, managing playlists, implementing search, handling webhooks). Create a site map showing how they link together.

## What's Next

In the next lesson, you will learn how to write an effective getting started guide that gets developers to their first successful API call quickly.