Expert REST API Documentation Exercises

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:

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:

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:

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:

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: