API Documentation Template

API Information

• Version: API Version, e.g. v1
• Base URL: Base URL, e.g. https://api.example.com/v1
• Content Type: application/json

Authentication

• Type: Authentication Type, e.g. Bearer Token, API Key, OAuth2
• Header Format: Authorization: Bearer YOUR_TOKEN_HERE
• Token Format: Token Format Details

Endpoints

Create Resource

POST /api/v1/resources

Request Headers

{
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TOKEN_HERE"
}

Request Body

{
    "name": "string",
    "description": "string",
    "type": "string"
}

Response

{
    "data": {
        "id": "resource-id",
        "name": "string",
        "description": "string",
        "type": "string",
        "createdAt": "2024-02-04T10:00:00Z"
    },
    "meta": {
        "timestamp": "2024-02-04T10:00:00Z"
    }
}

Get Resource

GET /api/v1/resources/RESOURCE_ID

Parameters

Name	Type	Required	Description
id	string	Yes	Resource identifier

Response

{
    "data": {
        "id": "resource-id",
        "name": "string",
        "description": "string",
        "type": "string",
        "createdAt": "2024-02-04T10:00:00Z"
    }
}

List Resources

GET /api/v1/resources

Query Parameters

Name	Type	Required	Description
page	number	No	Page number
limit	number	No	Items per page
sort	string	No	Sort field
order	string	No	Sort order (asc/desc)

Response

{
    "data": [
        {
            "id": "resource-id",
            "name": "string",
            "type": "string",
            "createdAt": "2024-02-04T10:00:00Z"
        }
    ],
    "meta": {
        "pagination": {
            "total": 100,
            "page": 1,
            "perPage": 10,
            "totalPages": 10
        }
    }
}

Error Responses

Standard Error Format

{
    "error": {
        "code": "ERROR_CODE",
        "message": "Error message description",
        "details": {
            "field": "Field with error",
            "reason": "Error reason"
        }
    }
}

Common Error Codes

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
500	Internal Server Error

Versioning

URL Versioning

Example: https://api.example.com/v1/resources

Header Versioning

Example: Accept: application/vnd.company.api+json;version=1

Rate Limiting

• Rate: Rate Limit, e.g. 100 requests per minute
• Headers:
  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Time until limit resets

Pagination

• Query Parameters:
  • page: Page number
  • limit: Items per page
• Response Headers:
  • X-Total-Count: Total number of items
  • Link: Links to first, prev, next, last pages

Usage Guide

When to Use

• Creating new API endpoints
• Documenting existing APIs
• Updating API documentation
• Sharing API specs with team

Best Practices

1. Documentation

   • Be comprehensive
   • Include examples
   • Show request/response
   • List all parameters

2. Endpoints

   • Clear descriptions
   • Complete parameters
   • Response formats
   • Error scenarios

3. Examples

   • Real use cases
   • Valid data
   • Common scenarios
   • Error cases

4. Updates

   • Version changes
   • Breaking changes
   • Deprecations
   • Migration guides

Example Implementation

Authentication Endpoint

Request

{
    "email": "[email protected]",
    "password": "securepassword123"
}

Response

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.token",
    "user": {
        "id": "user-123",
        "email": "[email protected]",
        "name": "John Doe",
        "created_at": "2024-02-04T10:00:00Z"
    }
}

Error Response Example

{
    "error": {
        "code": "auth_failed",
        "message": "Invalid email or password",
        "details": {
            "field": "password",
            "reason": "incorrect"
        }
    }
}