Skip to main content

API Documentation Standards

In This Document​

API Documentation Purpose​

Comprehensive API documentation serves several critical purposes:

  1. Developer Usability: Makes APIs easy to understand and use
  2. Consistency: Ensures consistent API design and usage
  3. Onboarding: Accelerates new developer productivity
  4. Testing: Provides a reference for test development
  5. Integration: Simplifies integration with external systems

API Documentation Requirements​

OpenAPI/Swagger Documentation​

All REST APIs must be documented using OpenAPI/Swagger:

  • Use OpenAPI 3.0 or later specification
  • Document all endpoints, including internal ones
  • Generate interactive documentation for testing
  • Include the specification in the codebase
  • Keep documentation in sync with implementation

Required Information for Each Endpoint​

Every API endpoint must document:

Basic Endpoint Information​

  • URL Path: The full path including version (e.g., /api/v3/users)
  • HTTP Method: GET, POST, PUT, DELETE, etc.
  • Summary: Brief description of the endpoint's purpose
  • Description: Detailed explanation of the endpoint's functionality
  • Tags: Logical grouping of endpoints (e.g., "Users", "Products")
  • Deprecated: Flag if the endpoint is deprecated, with migration path

API Documentation Format​

OpenAPI Structure​

Our OpenAPI documentation follows this structure:

openapi: 3.0.0
info:
  title: API Name
  description: Comprehensive description of the API
  version: 1.0.0
servers:
  - url: https://api.example.com/v3
    description: Production server
  - url: https://staging-api.example.com/v3
    description: Staging server
paths:
  /resource:
    get:
      summary: Brief description
      description: Detailed description
      parameters:
        # Parameters definition
      responses:
        # Responses definition
components:
  schemas:
    # Reusable schemas
  securitySchemes:
    # Security definitions

Naming Conventions​

  • Endpoints: Use plural nouns for resources (e.g., /users not /user)
  • Parameters: Use camelCase for parameter names
  • Schemas: Use PascalCase for schema names
  • Properties: Use camelCase for property names
  • Enums: Use PascalCase for enum names, UPPER_SNAKE_CASE for values

Documentation Tools​

  • Swagger UI: Interactive documentation for testing
  • Redoc: User-friendly documentation for consumers
  • Swagger Editor: For creating and editing OpenAPI specs
  • Swagger Codegen: For generating client libraries
  • Postman: For testing and documenting APIs

Documentation Process​

Creating Documentation​

  1. Start with API design before implementation
  2. Document endpoints as they are implemented
  3. Include documentation in pull requests
  4. Review documentation as part of code review
  5. Generate and publish updated documentation on merge

Maintaining Documentation​

  • Update documentation when API changes
  • Version documentation alongside API versions
  • Mark deprecated endpoints with migration paths
  • Review documentation quarterly for accuracy
  • Collect and incorporate user feedback

API Versioning​

Our API versioning strategy:

  • Use semantic versioning (MAJOR.MINOR.PATCH)
  • Include version in URL path (e.g., /api/v3/users)
  • Document breaking changes between versions
  • Maintain documentation for all supported versions
  • Include deprecation notices and timelines

API Changelog​

Maintain an API changelog that includes:

  • Version number and release date
  • New endpoints and features
  • Modified endpoints with change details
  • Deprecated endpoints with migration paths
  • Breaking changes with migration guides
  • Bug fixes related to API behavior

API Documentation Examples​

Example Endpoint Documentation​

/users/{id}:
  get:
    summary: Get user by ID
    description: Retrieves a user by their unique identifier
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: The user's unique identifier
    responses:
      '200':
        description: Successful operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            example:
              id: 123
              name: John Doe
              email: john@example.com
              created_at: "2023-01-15T14:30:00Z"
      '404':
        description: User not found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'
            example:
              code: 404
              message: User not found
    security:
      - bearerAuth: []

Integration with Development Process​

API documentation is integrated with our development process:

  • Include API documentation requirements in task definitions
  • Generate documentation from code annotations where possible
  • Validate API documentation as part of CI/CD pipeline
  • Test documented examples in automated tests
  • Review API design before implementation
Last updated on by Behnam Moradi