Tutorials and Examples — Teaching Developers with Real-World Code

In this tutorial, you will learn about Tutorials and Examples. We cover key concepts, practical examples, and best practices to help you master this topic.

API tutorials teach developers to accomplish specific tasks using your API through complete, runnable code examples that solve real problems from start to finish.

In this tutorial, you will learn how to write effective tutorials, structure them for learning, choose appropriate examples, and organize them into a coherent learning path.

What You'll Learn

You will learn the structure of effective API tutorials, how to choose examples that match developer needs, how to write step-by-step instructions, and how to organize tutorials into learning paths.

Why It Matters

Tutorials convert developers from curious visitors to active users. A developer who completes a tutorial has invested time in your API and is far more likely to build with it than one who only reads reference docs.

Real-World Use

DodaTech documentation includes tutorials for the five most common integration patterns: user management, file uploads, Webhook processing, search implementation, and reporting. Each tutorial takes 15-30 minutes to complete and includes downloadable code.

flowchart LR
  A[Learning Path] --> B[Beginner Tutorials]
  A --> C[Intermediate Tutorials]
  A --> D[Advanced Tutorials]
  B --> E[Getting Started]
  B --> F[CRUD Operations]
  C --> G[File Uploads]
  C --> H[Webhooks]
  D --> I[Batch Processing]
  D --> J[Custom Integrations]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Tutorial Structure

Every tutorial should follow this structure:

# Tutorial: Uploading Files to DodaTech

## What You Will Build
A Python script that uploads files to DodaTech cloud storage,
generates shareable links, and handles upload errors gracefully.

## Prerequisites
- DodaTech API key with files:write scope
- Python 3.8+
- A test file to upload (any file under 10MB)

## Step 1: Set Up Authentication

```python
import requests

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

def get_headers():
    return {
        "X-API-Key": API_KEY,
        "Accept": "application/json"
    }

Step 2: Upload a File

def upload_file(file_path):
    url = f"{BASE_URL}/files/upload"
    with open(file_path, "rb") as f:
        files = {"file": f}
        response = requests.post(url, headers=get_headers(), files=files)

    if response.status_code == 201:
        return response.json()
    else:
        raise Exception(f"Upload failed: {response.json()['message']}")

# Test the upload
result = upload_file("test-document.pdf")
print(f"File ID: {result['id']}")
print(f"URL: {result['url']}")
# Expected: File ID: file_abc123, URL: https://storage.dodatech.com/files/file_abc123

Step 3: Generate Shareable Link

def create_share_link(file_id, expires_in_hours=24):
    url = f"{BASE_URL}/files/{file_id}/share"
    response = requests.post(url, headers=get_headers(), json={
        "expiresIn": expires_in_hours * 3600,
        "permissions": ["view", "download"]
    })

    if response.status_code == 201:
        return response.json()["shareUrl"]
    else:
        raise Exception(f"Share link creation failed")

share_url = create_share_link(result["id"])
print(f"Share URL (expires in 24h): {share_url}")
# Expected: Share URL (expires in 24h): https://dodatech.com/s/abc123xyz

Step 4: Handle Errors

def upload_file_safe(file_path):
    try:
        return upload_file(file_path)
    except requests.exceptions.RequestException as e:
        print(f"Network error: {e}")
        return None
    except Exception as e:
        print(f"Upload error: {e}")
        return None

# Test error handling
result = upload_file_safe("nonexistent.pdf")
print(f"Result: {result}")
# Expected: Upload error: [Errno 2] No such file or directory: 'nonexistent.pdf'
# Expected: Result: None

Complete Script

Here is the complete script that combines all steps:

import requests

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

def get_headers():
    return {"X-API-Key": API_KEY, "Accept": "application/json"}

def upload_file(file_path):
    with open(file_path, "rb") as f:
        response = requests.post(
            f"{BASE_URL}/files/upload",
            headers=get_headers(),
            files={"file": f}
        )
    response.raise_for_status()
    return response.json()

def create_share_link(file_id, expires_in_hours=24):
    response = requests.post(
        f"{BASE_URL}/files/{file_id}/share",
        headers=get_headers(),
        json={"expiresIn": expires_in_hours * 3600, "permissions": ["view", "download"]}
    )
    response.raise_for_status()
    return response.json()["shareUrl"]

if __name__ == "__main__":
    import sys
    file_path = sys.argv[1]
    result = upload_file(file_path)
    share_url = create_share_link(result["id"])
    print(f"Uploaded: {result['name']}")
    print(f"Share: {share_url}")

Run it: python3 upload.py test-document.pdf

## Choosing Tutorial Topics

Select tutorial topics based on:

**Developer demand**: What do developers ask about in support tickets? Each recurring question is a tutorial topic.

**Integration patterns**: What are the primary use cases for your API? File upload, search, authentication, reporting.

**Competition**: What tutorials do competing APIs offer? Cover the same topics with your unique features.

**Complexity**: Start with simple tutorials and progress to complex ones. Each tutorial should build on the previous.

## Tutorial Organization

Organize tutorials into a learning path:

Getting Started (5 min) └── Authentication (10 min) ├── CRUD Operations (15 min) │ ├── Search and Filtering (20 min) │ └── File Uploads (20 min) ├── Webhooks (25 min) └── Batch Processing (30 min)

Label each tutorial with difficulty and estimated time.

## Interactive Tutorial Elements

Add interactive elements to increase engagement:

```html
<!-- Step-by-step progress indicator -->
<div class="tutorial-progress">
  <div class="step active">1. Setup</div>
  <div class="step">2. Code</div>
  <div class="step">3. Test</div>
  <div class="step">4. Deploy</div>
</div>

<!-- Copy button on code blocks -->
<button class="copy-btn" onclick="copyCode(this)">
  Copy Code
</button>

Common Mistakes

1. Incomplete code examples — Showing snippets that do not run on their own. Every code block should be part of a complete, runnable script.

2. No expected output — Telling developers to run code but not showing what they should see. Developers cannot verify they succeeded.

3. Tutorials that do not work — Publishing tutorials without testing them end-to-end against the live API. Test every tutorial before publishing.

4. Too many steps — Creating tutorials with 15-plus steps. Break long tutorials into multiple linked tutorials.

5. No downloadable code — Making developers type code manually. Provide a link to download the complete tutorial code.

Practice Questions

1. What is the recommended structure for an API tutorial?
2. How do you choose topics for tutorials?
3. Why should every code block show expected output?
4. How do you organize tutorials into a learning path?
5. What makes a tutorial effective versus ineffective?

Challenge

Write a tutorial for bulk data export using a file storage API. The tutorial should export all files from a user account, handle pagination, download each file, handle rate limits with retry logic, and generate a summary report. Include a complete, runnable Python script with expected output for each step.

FAQ

Mini Project

Write a three-part tutorial series for a messaging API. Part 1: Sending and receiving messages. Part 2: Managing conversations and threads. Part 3: Implementing real-time notifications with Webhooks. Each tutorial should include a complete runnable script, expected output, and a link to the next tutorial.

What's Next

In the next lesson, you will learn how to write changelogs and deprecation notices that keep developers informed of API changes.