SDKs and Client Libraries — Complete Guide

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

SDK documentation covers installation, authentication, quickstart, full API reference, error handling, pagination, advanced usage patterns, and Migration guides for each client library so developers can integrate your API using idiomatic code in their preferred language.

What You'll Learn

How to structure SDK documentation, what to include in installation and setup guides, how to write quickstart examples that produce visible output fast, how to document SDK methods and classes, and how to generate SDK reference docs from source code annotations.

Why It Matters

SDK documentation is the primary way most developers interact with your API. A well-documented SDK with clear quickstart, complete reference, and working examples reduces integration time from hours to minutes and increases API adoption significantly.

Real-World Use

The DodaTech Python SDK documentation includes installation via pip, client initialization with environment variables, a three-line quickstart, and a complete API reference generated from docstrings. Doda Browser and DodaZIP both use the same SDK, and their teams contribute to the docs.

SDK Documentation Structure

flowchart TD
  A[SDK Documentation] --> B[Installation]
  A --> C[Authentication]
  A --> D[Quickstart]
  A --> E[API Reference]
  A --> F[Error Handling]
  A --> G[Advanced Usage]
  A --> H[Migration Guides]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Installation Guide

Show the fastest install command, then optional methods.

# Install the DodaTech Python SDK
pip install dodatech-sdk

# For a specific version
pip install dodatech-sdk==2.1.0

# For development (latest main branch)
pip install git+https://github.com/dodatech/dodatech-python.git

# Verify installation
python -c "import dodatech; print(dodatech.__version__)"
# Expected output: 2.1.0

Authentication Setup

Show how to initialize the client with API keys from environment variables.

import os
from dodatech import Client

# Recommended: read API key from environment variable
client = Client(api_key=os.environ["DODATECH_API_KEY"])

# Alternative: direct key (not recommended for production)
client = Client(api_key="your-api-key-here")

Quickstart

The quickstart should do something useful in under 5 lines.

import os
from dodatech import Client

client = Client(api_key=os.environ["DODATECH_API_KEY"])
files = client.files.list(per_page=5)

for file in files:
    print(f"{file.name}: {file.size_bytes} bytes")

# Expected output:
# report.pdf: 1048576 bytes
# data.csv: 256000 bytes
# image.png: 5242880 bytes

API Reference

Reference the SDK methods with parameters, return types, and examples.

class Client:
    def files(self) -> FilesAPI:
        """Access file-related API operations."""
        pass

class FilesAPI:
    def list(
        self,
        page: int = 1,
        per_page: int = 20,
        sort: str = "created_at",
        status: str = "all"
    ) -> list[File]:
        """List files in your organization.

        Args:
            page: Page number (default: 1)
            per_page: Items per page, max 100 (default: 20)
            sort: Sort field (created_at, name, size)
            status: Filter by status (active, archived, deleted)

        Returns:
            List of File objects

        Raises:
            AuthenticationError: Invalid API key
            RateLimitError: Too many requests
        """
        pass

    def compress(
        self,
        file_url: str = None,
        file: BinaryIO = None,
        format: str = "zip",
        level: int = 6,
        password: str = None
    ) -> Job:
        """Compress a file.

        Args:
            file_url: Public URL of the file to compress
            file: Binary file for direct upload
            format: Output format (zip, gzip, sevenz)
            level: Compression level 1-9
            password: Optional encryption password

        Returns:
            Job object with progress information
        """
        pass

Error Handling

Show idiomatic error handling for the SDK.

from dodatech import Client, AuthenticationError, RateLimitError, ApiError

client = Client(api_key="YOUR_KEY")

try:
    files = client.files.list()
except AuthenticationError:
    print("Invalid API key. Generate a new one from the dashboard.")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds.")
except ApiError as e:
    print(f"API error {e.status_code}: {e.code}")
    print(f"See: {e.docs_url}")
except Exception as e:
    print(f"Unexpected error: {e}")

Advanced Usage

Document patterns like pagination, async processing, and batching.

# Pagination: iterate through all pages automatically
from dodatech import Client

client = Client(api_key="YOUR_KEY")
all_files = []

for page in client.files.list(per_page=100):
    all_files.extend(page)
    print(f"Fetched {len(page)} files (total: {len(all_files)})")

# Wait for async job completion
job = client.files.compress(file_url="https://example.com/big_file.mp4")
job.wait_for_completion(poll_interval=5, timeout=300)
print(f"Compressed: {job.download_url}")

Common Mistakes

1. No Quickstart

SDK documentation that starts with API reference instead of a working example forces developers to piece together how to use the library.

2. Missing Installation Instructions

Assuming developers know how to install the SDK leads to first-request failures. Show the exact pip or npm command.

3. No Environment Variable Best Practices

Examples with hardcoded API keys normalize bad security habits. Always use environment variables and placeholders.

4. Incomplete Error Handling

SDK examples without error handling teach developers to ignore failures. Show try-catch blocks for common error types.

5. No Version Compatibility Notes

Not documenting which SDK version works with which API version causes version mismatch errors.

6. Missing Advanced Patterns

Showing only basic usage without pagination, retry, or async patterns forces developers to discover these on their own.

7. No Migration Guide

Updating the SDK without migration docs breaks existing integrations. Document breaking changes and upgrade paths.

Practice Questions

1. What three sections should every SDK documentation include?

Installation (pip/npm command), authentication (client initialization with API key), and quickstart (5-line example that produces output).

2. Why should SDK examples use environment variables for API keys?

Environment variables keep keys out of source code, preventing accidental commits to version control. Hardcoded keys in examples teach bad security habits.

3. What is the purpose of SDK API reference documentation?

The reference documents every method, parameter, return type, and exception. It is the authoritative source for SDK usage details, generated from source code annotations.

4. How do you document pagination in an SDK?

Show how to iterate through all pages, either with automatic pagination (for page in client.files.list()) or manual pagination with page and per_page parameters.

5. Challenge: Write SDK documentation for one client library including installation, authentication, quickstart, API reference for three methods, error handling, and one advanced usage pattern.

FAQ

Mini Project: Write SDK Documentation

Create complete SDK documentation for a fictional client library. Include installation guide, authentication, three-line quickstart, API reference for five methods, error handling with try-catch examples, advanced pagination, and a migration guide from v1 to v2.

What's Next

SDKs simplify integration. Now learn to communicate API evolution with Changelog and Release Notes. Then explore Migration Guides for helping developers upgrade between API versions.