2. General API Design Guidelines

2.1 API First Principle

Overview

The API First principle means that APIs should be designed as contracts before implementation begins.

The API specification is the primary artifact of API development and should be treated as the source of truth throughout the API lifecycle.

By designing APIs first, teams can:

• Establish clear communication between API providers and consumers
• Enable parallel development across different teams
• Reduce integration risks
• Improve API consistency and maintainability

Requirements

Define APIs Before Implementation

APIs should be designed before writing implementation code.

The API contract should define:

• Resources and endpoints
• HTTP methods
• Request and response models
• Data schemas
• Error handling behavior
• Security requirements
• Versioning strategy

The API specification should be created using OpenAPI as the API description language.

Recommended workflow:

API Design
    |
    v
OpenAPI Specification
    |
    v
API Review
    |
    v
Implementation
    |
    v
Testing and Validation

Follow API Design Guidelines

API designs should follow established RESTful API design principles.

API specifications should be validated using automated API linting tools.

API linting helps identify:

• Naming inconsistencies
• Missing metadata
• Incorrect HTTP semantics
• Inconsistent resource modeling
• Documentation issues
• Compatibility risks

Automated validation should be integrated into the API development lifecycle.

Conduct Early API Reviews

For APIs consumed by external clients, early review feedback should be collected from:

• API consumers
• Client developers
• Peer reviewers

Early API reviews help identify design problems before implementation and reduce the cost of later changes.

Review activities should focus on:

• API usability
• Resource modeling
• Request and response design
• Client compatibility
• Long-term maintainability

2.2 API Specification Using OpenAPI

Overview

OpenAPI is the recommended standard for describing RESTful API contracts.

API specifications should be provided using a self-contained OpenAPI document.

Example:

openapi: 3.0.3

info:
  title: User API
  version: 1.0.0

paths:
  /users:
    get:
      summary: Retrieve users
      responses:
        "200":
          description: Successful response

A well-defined OpenAPI specification enables:

• API documentation generation
• Client SDK generation
• API validation
• Automated testing
• Better collaboration between teams

OpenAPI Version Selection

New APIs

New APIs should use OpenAPI 3.0 or later.

OpenAPI 3.0 provides broad ecosystem support and should be the default choice for most API projects.

Legacy APIs

Existing APIs based on older specifications may continue using their current format.

However, new API development should avoid introducing outdated specification formats.

OpenAPI 3.1 Considerations

OpenAPI 3.1 may be adopted when:

• Advanced JSON Schema compatibility is required
• Migration from other API specification formats is needed
• Supporting tools provide sufficient compatibility

Before adopting OpenAPI 3.1, teams should verify compatibility with:

• Documentation tools
• Code generators
• API gateways
• Validation tools

Tool Compatibility Considerations

The selected OpenAPI version should consider the intended usage scenarios.

Examples:

Schema Design Considerations

Although OpenAPI supports advanced schema composition features, teams should carefully evaluate tool support before using:

• oneOf
• anyOf
• allOf
• not

Heavy dependency on unsupported schema features may reduce compatibility with:

• Generated SDKs
• Client applications
• API tooling

2.3 API User Documentation

Overview

For external APIs, API specifications should be complemented with API user documentation.

OpenAPI describes the technical API contract, while user documentation provides additional context to help developers understand and correctly use the API.

A good API user manual improves developer experience, especially for developers who are unfamiliar with the API domain.

Recommended Documentation Content

A useful API user manual typically includes the following information.

API Scope and Purpose

Documentation should explain:

• API responsibilities
• Supported business scenarios
• Target consumers
• Common use cases

Example:

The User API provides operations for managing user lifecycle information.

API Usage Examples

Documentation should provide practical examples:

• Request examples
• Response examples
• Authentication examples
• Common workflows

Example:

GET /users/123

Response:

{
  "id": "123",
  "name": "Alice"
}

Error Handling and Troubleshooting

Documentation should describe:

• Error codes
• Error messages
• Possible causes
• Recovery actions

Example:

Architecture Context

For complex APIs, documentation should provide:

• System architecture diagrams
• Service dependencies
• Data flow descriptions
• Integration relationships

Example:

Client
  |
  | REST API
  |
API Gateway
  |
Backend Service
  |
Database

Sequence Flow Examples

For complex workflows, sequence diagrams should be provided.

Example:

sequenceDiagram
    participant Client
    participant API
    participant Service

    Client->>API: Send Request
    API->>Service: Process Request
    Service-->>API: Return Result
    API-->>Client: Response

Summary

A well-designed RESTful API should follow these principles:

The goal is to create APIs that are:

• Consistent
• Maintainable
• Discoverable
• Evolvable
• Easy for developers to consume

A successful API is not only technically functional, but also provides a clear, stable, and predictable contract for all consumers.