Expert REST API Documentation Exercises

Master complex API documentation with these 5 expert-level exercises. Practice documenting GraphQL, gRPC, API versioning, security, and performance optimization for real-world scenarios.

Congratulations on reaching the Expert Level!

So far, you’ve built a strong foundation in API documentation. You’ve learned about API structure, authentication, rate limits, pagination, error handling, and even mastered cURL. Now, it’s time to apply your knowledge in real-world scenarios and tackle complex API documentation challenges.

Simulating Real-World Documentation Challenges

These expert-level exercises simulate actual documentation tasks you might encounter as a senior technical writer. They include incomplete information, complex architectures, and emerging technologies - just like in the real world.

What You’ll Document in These Expert Exercises

In this chapter, you’ll work through 5 sophisticated exercises that will prepare you for advanced API documentation roles:

Document a GraphQL API with complex queries and mutations
Create gRPC API documentation with protocol buffers
Build versioning and deprecation documentation for evolving APIs
Develop comprehensive security documentation for enterprise APIs
Create performance optimization guidance for API consumers

These exercises represent the cutting edge of API technologies and documentation challenges.

What Makes These Exercises “Expert Level”?

Feature	Intermediate Level	Expert Level
API Technologies	REST APIs only	REST, GraphQL, gRPC, WebSockets
Documentation Scope	Endpoint-focused	Full API lifecycle and ecosystem
Information Provided	Mostly complete	Intentionally incomplete
Decision Making	Some autonomy	Requires significant judgment
Technical Depth	Application-level concepts	Architecture and system design concepts
Target Audience	Developers	Developers, architects, and DevOps engineers

Exercise Overview

Exercise	Focus Area	Key Skills Practiced	Difficulty
Exercise 1	GraphQL Movie Database API	Query/mutation documentation, schema explanation	Hard
Exercise 2	gRPC Communication Service	Protocol buffers, streaming, service definition	Hard
Exercise 3	API Versioning & Deprecation	Migration guides, backwards compatibility	Hard
Exercise 4	API Security Documentation	OAuth flows, token management, OWASP	Expert
Exercise 5	API Performance Optimization	Caching, compression, batch operations	Expert

Strategies for Tackling Expert-Level Documentation

These exercises are intentionally challenging. Here are some strategies to approach them effectively:

Research thoroughly - You may need to research technologies or concepts that are unfamiliar
Fill in the gaps - Like real-world documentation tasks, these exercises may have incomplete information
Consider multiple audiences - Different stakeholders need different levels of technical detail
Add value beyond the requirements - Look for opportunities to make the documentation more helpful
Balance technical accuracy with clarity - Even complex concepts need clear explanation
Use visual aids - Diagrams, flowcharts, and other visuals can explain complex relationships

Remember that expert-level API documentation isn’t just about documenting what exists—it’s about helping developers understand why it exists and how to use it effectively.

Let’s Begin!

Each exercise below can be expanded to view the requirements and solution. These are significant challenges that reflect real-world complexity, so take your time with each one.

1 Documenting a GraphQL API for a Movie Database

Challenge: Document a GraphQL API for a Movie Database

Scenario: You have been asked to document a GraphQL API for a **Movie Database** service. Users can:

Retrieve movie details by title or ID.
Search for movies by genre, actor, or director.
Add reviews for movies.

GraphQL Schema (To be documented)

        type Movie {
            id: ID!
            title: String!
            genre: String
            director: String
            releaseYear: Int
            rating: Float
        }

        type Query {
            getMovieById(id: ID!): Movie
            searchMovies(genre: String, director: String, actor: String): [Movie]
        }

        type Mutation {
            addReview(movieId: ID!, rating: Float!, comment: String): ReviewResponse
        }

        type ReviewResponse {
            success: Boolean!
            message: String!
        }

Your Task:

Write a complete API documentation page covering:

Overview - Describe the API and its purpose.
GraphQL Endpoints - Explain how to query and mutate data.
Authentication - Describe how users authenticate (e.g., API Key, OAuth).
Request & Response Formats - Document how users should send queries and handle responses.
Error Handling - Provide guidance on common GraphQL errors.

Hint: Use GraphQL best practices and real-world examples to make the documentation clear.

Solution: GraphQL API Documentation for Movie Database

1. Overview

The **Movie Database GraphQL API** allows users to fetch movie details, search movies, and add reviews.

2. Querying Data

Use the **GraphQL Query Type** to retrieve movie information:

        query {
            getMovieById(id: "tt1234567") {
                title
                genre
                director
                releaseYear
            }
        }

3. Searching for Movies

Search movies by genre, director, or actor:

        query {
            searchMovies(genre: "Action") {
                title
                director
            }
        }

4. Adding a Review (Mutation)

Users can submit a review using a **GraphQL Mutation**:

        mutation {
            addReview(movieId: "tt1234567", rating: 4.5, comment: "Great movie!") {
                success
                message
            }
        }

5. Authentication

The API requires an API key for authentication. Pass the key in the request header:

        headers: {
            "Authorization": "Bearer YOUR_API_KEY"
        }

6. Error Handling

Common GraphQL API errors and their meanings:

Error Code	Message	Reason
401	Unauthorized	Invalid API Key
404	Movie Not Found	The requested movie ID does not exist.

2 Documenting a gRPC Communication Service

Challenge: Document a gRPC API for a Payment Processing Service

Scenario: You have been asked to document a **gRPC API** for a **Payment Processing Service**. Users can:

Process a payment using a card or bank transfer.
Check the status of a payment by transaction ID.
Retrieve a list of all past transactions for a user.

gRPC Service Definition (To be documented)

        syntax = "proto3";

        service PaymentService {
            rpc ProcessPayment (PaymentRequest) returns (PaymentResponse);
            rpc GetPaymentStatus (PaymentStatusRequest) returns (PaymentStatusResponse);
            rpc GetTransactionHistory (TransactionHistoryRequest) returns (TransactionHistoryResponse);
        }

        message PaymentRequest {
            string user_id = 1;
            string payment_method = 2;
            float amount = 3;
            string currency = 4;
        }

        message PaymentResponse {
            bool success = 1;
            string transaction_id = 2;
            string message = 3;
        }

        message PaymentStatusRequest {
            string transaction_id = 1;
        }

        message PaymentStatusResponse {
            string transaction_id = 1;
            string status = 2;
            string message = 3;
        }

        message TransactionHistoryRequest {
            string user_id = 1;
        }

        message TransactionHistoryResponse {
            repeated PaymentResponse transactions = 1;
        }

Your Task:

Write a complete API documentation page covering:

Overview - Describe the API and its purpose.
Service Definitions - Explain the gRPC services and methods.
Authentication - Describe how users authenticate (e.g., API Key, TLS).
Request & Response Formats - Document message structures.
Error Handling - Provide guidance on common gRPC errors.

Hint: Use gRPC best practices and real-world examples to make the documentation clear.

Solution: gRPC API Documentation for Payment Processing

1. Overview

The **Payment Processing gRPC API** allows users to process payments, check status, and retrieve transaction history.

2. Service Definitions

Use the **gRPC Service** to send and retrieve payment data:

        rpc ProcessPayment (PaymentRequest) returns (PaymentResponse);
        rpc GetPaymentStatus (PaymentStatusRequest) returns (PaymentStatusResponse);
        rpc GetTransactionHistory (TransactionHistoryRequest) returns (TransactionHistoryResponse);

3. Processing a Payment

Clients can process payments by calling the `ProcessPayment` method:

        {
            "user_id": "12345",
            "payment_method": "credit_card",
            "amount": 50.00,
            "currency": "USD"
        }

4. Checking Payment Status

Check the status of a transaction:

        {
            "transaction_id": "txn_98765"
        }

5. Authentication

The API requires authentication via TLS or API keys:

        metadata: {
            "Authorization": "Bearer YOUR_API_KEY"
        }

6. Error Handling

Common gRPC API errors and their meanings:

Error Code	Message	Reason
UNAUTHENTICATED	Invalid API Key	Access denied
NOT_FOUND	Transaction Not Found	Invalid transaction ID

3 Documenting API Versioning and Deprecation

Expert-Level API Documentation - Exercise 3

Challenge: Document API Versioning & Deprecation for a User Management API

Scenario: The **User Management API** is upgrading from **v1 to v2**, introducing new features and removing old ones.

Changes in v2:

The `/users/{id}` endpoint now returns an **email field**.
The `/users/{id}/profile` endpoint is being **deprecated**.
Authentication is now **mandatory** via API Key.

API Versioning Strategy

The API supports multiple versions using:

URI Versioning: /v1/users/{id} → /v2/users/{id}
Query Parameter Versioning: /users/{id}?version=2
Header Versioning: Accept: application/vnd.api+json; version=2

Your Task:

Write a complete API documentation page covering:

Overview - Explain why versioning is necessary.
Versioning Methods - Describe the API versioning strategy.
Deprecation Notices - Guide users on handling deprecated endpoints.
Backward Compatibility - Explain how to migrate to v2 smoothly.

Hint: Use best practices to ensure developers transition smoothly.

Solution: API Versioning & Deprecation Documentation

1. Overview

The **User Management API v2** introduces enhancements while maintaining backward compatibility.

2. Versioning Strategy

We support the following versioning methods:

URI Versioning: Append the version to the URL.
Query Parameter: Specify the version as a query parameter.
Header Versioning: Use custom media type headers.

3. Deprecation Notices

The `/users/{id}/profile` endpoint is deprecated. Use `/users/{id}` instead.

4. Backward Compatibility

To migrate smoothly:

Start using `/v2/users/{id}` for retrieving user details.
Use API Key authentication.
Update any legacy requests that rely on the deprecated `/users/{id}/profile` endpoint.

5. Example Requests

v1 Request

        GET /v1/users/12345

v2 Request

        GET /v2/users/12345
        Authorization: Bearer YOUR_API_KEY

6. Error Handling

Common API versioning errors:

Error Code	Message	Reason
410	Gone	The requested API version is no longer supported.
400	Invalid Version	The provided version parameter is incorrect.

4 Documenting API Security Best Practices

Expert-Level API Documentation - Exercise 4

Challenge: Documenting Secure API Authentication

Scenario: A new API requires **secure authentication** using **OAuth 2.0 and JWT tokens**.

Security Features:

OAuth 2.0 authentication with **Authorization Code Flow**.
API requires **scopes and permissions** to control access.
JWT tokens expire after **1 hour** and must be refreshed.
API supports **Rate Limiting** (1000 requests/hour per user).

Your Task:

Write a complete API security documentation covering:

Authentication Flows - Explain OAuth 2.0 & API Key authentication.
Token Handling - Explain JWT tokens, expiry, and refresh mechanisms.
Rate Limiting - Document how users can handle API throttling.
Security Best Practices - Guide developers on securely accessing the API.

Hint: Use real-world security best practices for clarity.

Solution: API Security & OAuth Documentation

1. Authentication Flow (OAuth 2.0)

The API uses OAuth 2.0 with **Authorization Code Flow** for secure authentication.

🔹 Step 1: Get Authorization Code

        GET https://auth.example.com/oauth/authorize
        ?client_id=YOUR_CLIENT_ID
        &response_type=code
        &redirect_uri=https://yourapp.com/callback
        &scope=read write

🔹 Step 2: Exchange Code for Access Token

        POST https://auth.example.com/oauth/token
        Headers:
        Content-Type: application/x-www-form-urlencoded

        Body:
        client_id=YOUR_CLIENT_ID
        client_secret=YOUR_CLIENT_SECRET
        code=AUTHORIZATION_CODE
        redirect_uri=https://yourapp.com/callback
        grant_type=authorization_code

2. Handling JWT Tokens

Access tokens are **JWT-based**, valid for **1 hour**, and include user roles.

        {
            "access_token": "eyJhbGciOiJIUz...",
            "token_type": "Bearer",
            "expires_in": 3600
        }

3. Refreshing Expired Tokens

        POST https://auth.example.com/oauth/token
        Headers:
        Content-Type: application/x-www-form-urlencoded

        Body:
        client_id=YOUR_CLIENT_ID
        client_secret=YOUR_CLIENT_SECRET
        refresh_token=YOUR_REFRESH_TOKEN
        grant_type=refresh_token

4. Rate Limiting

Each user can send **1000 requests per hour**.

        Headers:
        X-RateLimit-Limit: 1000
        X-RateLimit-Remaining: 200
        X-RateLimit-Reset: 1678909876

5. Security Best Practices

Use **HTTPS** for all API calls.
Never expose **client secrets** in frontend code.
Always **refresh expired tokens** using the refresh token flow.
Implement **IP whitelisting** for API access.

6. Error Handling

Common API security errors and their meanings:

Error Code	Message	Reason
401	Unauthorized	Invalid API key or expired token.
403	Forbidden	User lacks required permissions.

5 Documenting API Performance Optimization

Expert-Level API Documentation - Exercise 5

Challenge: Documenting API Performance & Rate Limits

Scenario: A high-traffic API needs documentation on **performance best practices, rate limits, and bulk request handling.**

Performance Requirements:

API rate limits: **5000 requests per hour per user**.
Supports **Gzip compression** to reduce response payload size.
Clients should use **E-Tag caching** to avoid redundant requests.
API supports **bulk requests** (max **100 records per request**).
Pagination via **Cursor-based and Offset-based methods**.

Your Task:

Write a complete API documentation page covering:

Rate Limiting - Explain request limits & best practices.
Caching Mechanisms - Document E-Tag, Cache-Control, and Gzip support.
Bulk Requests - Guide users on batching API calls.
Pagination Methods - Explain Offset & Cursor pagination strategies.

Hint: Use real-world optimizations to improve API efficiency.

Solution: API Performance & Rate Limit Documentation

1. Rate Limiting

The API limits users to **5000 requests per hour** to prevent excessive load.

        Headers:
        X-RateLimit-Limit: 5000
        X-RateLimit-Remaining: 4500
        X-RateLimit-Reset: 1678909876

2. Caching Mechanisms

The API supports **E-Tag caching** and **Gzip compression**:

Using E-Tags:

        GET /data
        Headers:
        If-None-Match: "abc123"

Enabling Gzip Compression:

        GET /data
        Headers:
        Accept-Encoding: gzip

3. Bulk Requests

Clients can request **up to 100 records** per call:

        POST /bulk
        Body:
        {
            "requests": [
                {"id": 1}, {"id": 2}, {"id": 3}, ..., {"id": 100}
            ]
        }

4. Pagination Methods

The API supports **Offset and Cursor-based pagination**:

Offset Pagination:

        GET /users?limit=10&offset=20

Cursor Pagination:

        GET /users?cursor=abc123&limit=10

5. Best Practices for Performance Optimization

**Use Gzip compression** to reduce payload size.
**Leverage caching (E-Tag, If-Modified-Since) to minimize API calls.**
**Use pagination for large datasets to improve performance.**
**Batch multiple requests using bulk API calls.**
**Monitor rate limits & optimize requests accordingly.**

6. Error Handling

Common API rate limit errors:

Error Code	Message	Reason
429	Too Many Requests	Rate limit exceeded
400	Invalid Bulk Request	Exceeded max batch size (100 records)

Addressing Incomplete Information

In real-world API documentation, technical writers often receive incomplete information from developers. When you encounter gaps in these exercises, consider:

What would a developer need to know that isn’t stated?
What assumptions can you reasonably make based on industry standards?
What additional sections might you add to improve clarity?

This skill—identifying and filling information gaps—is essential for expert-level technical writers.

What’s Next?

After completing these expert-level exercises, you’ll be equipped to handle virtually any API documentation challenge. The next chapter on Testing APIs will show you how to verify your documentation accuracy by working directly with the APIs you document.

Key Takeaways

Expert API documentation requires understanding multiple API technologies beyond just REST
Documentation should cover the complete API lifecycle including versioning and deprecation
Security and performance considerations are critical components of advanced documentation
Real-world documentation often requires filling in gaps with research and reasonable assumptions
Effective API documentation serves multiple audiences with different technical backgrounds

Advanced API Technologies Resources

Expand your knowledge of advanced API technologies with these resources.

External Resources

Tools & APIs

Start your learning journey!

Course Progress 0%

0 of 0 pages completed

Found value in the course?

Your support fuels my work!

Have an issue?

Help improve the course by reporting an issue

Expert REST API Documentation Exercises

Table of Contents

What You’ll Document in These Expert Exercises

What Makes These Exercises “Expert Level”?

Exercise Overview

Strategies for Tackling Expert-Level Documentation

Let’s Begin!

1 Documenting a GraphQL API for a Movie Database

Challenge: Document a GraphQL API for a Movie Database

GraphQL Schema (To be documented)

Your Task:

Solution: GraphQL API Documentation for Movie Database

1. Overview

2. Querying Data

3. Searching for Movies

4. Adding a Review (Mutation)

5. Authentication

6. Error Handling

2 Documenting a gRPC Communication Service

Challenge: Document a gRPC API for a Payment Processing Service

gRPC Service Definition (To be documented)

Your Task:

Solution: gRPC API Documentation for Payment Processing

1. Overview

2. Service Definitions

3. Processing a Payment

4. Checking Payment Status

5. Authentication

6. Error Handling

3 Documenting API Versioning and Deprecation

Challenge: Document API Versioning & Deprecation for a User Management API

Changes in v2:

API Versioning Strategy

Your Task:

Solution: API Versioning & Deprecation Documentation

1. Overview

2. Versioning Strategy

3. Deprecation Notices

4. Backward Compatibility

5. Example Requests

v1 Request

v2 Request

6. Error Handling

4 Documenting API Security Best Practices

Challenge: Documenting Secure API Authentication

Security Features:

Your Task:

Solution: API Security & OAuth Documentation

1. Authentication Flow (OAuth 2.0)

🔹 Step 1: Get Authorization Code

🔹 Step 2: Exchange Code for Access Token

2. Handling JWT Tokens

3. Refreshing Expired Tokens

4. Rate Limiting

5. Security Best Practices

6. Error Handling

5 Documenting API Performance Optimization

Challenge: Documenting API Performance & Rate Limits

Performance Requirements:

Your Task:

Solution: API Performance & Rate Limit Documentation

1. Rate Limiting

2. Caching Mechanisms

Using E-Tags:

Enabling Gzip Compression:

3. Bulk Requests

4. Pagination Methods

Offset Pagination:

Cursor Pagination:

5. Best Practices for Performance Optimization

6. Error Handling

Addressing Incomplete Information

What’s Next?

Key Takeaways

Advanced API Technologies Resources

External Resources

Tools & APIs

Found value in the course?

Have an issue?

Support This Project