API Design Principles

A concise guide to API usability, discoverability, and consistency grounded in proven design philosophies and user needs.

Outcomes

Better understanding of API design principles principles

How it works

Steps

Consumer-first design: start every APIOps cycle by gathering user goals and domain terms so APIs solve real problems.
Consistent naming and behavior: apply shared conventions for resources, errors and formats to make APIs predictable.
Contract driven: capture the interface with OpenAPI or AsyncAPI before coding to align teams and enable automation.
Usability and discoverability: provide clear documentation and examples so developers quickly understand how to use the API.
Iterate safely: evolve designs in small, versioned increments so changes do not disrupt existing consumers.

API Style Guide

This guide outlines best practices and standards for designing and implementing RESTful APIs to ensure security, consistency, usability, and alignment with organizational goals. It also aligns with the API Audit Checklist.

1. Security and Privacy

HTTPS Enforcement

All APIs must enforce HTTPS to encrypt data in transit.
Sensitive information (e.g., tokens, credentials, personal data) must never be transmitted in URLs or query parameters. Use the request body for such data.

Role-Based Access Control (RBAC)

Implement RBAC using identity providers and enforce permissions within the API logic.
Document role-specific access controls in the API documentation.
Maturity Levels:
- Foundational: Roles are defined and access is manually enforced.
- Growing: Identity providers are integrated.
- Scaling: Dynamic role checks based on API consumers.
- Innovating: Automated, policy-driven RBAC enforcement.

OWASP API Security Compliance

Address OWASP API Security Top 10 risks, including:
- API6:2023 – Unrestricted Access to Sensitive Business Flows: Restrict sensitive business flows with proper authentication and authorization.
- API7:2023 – Server-Side Request Forgery (SSRF): Validate inputs and sanitize responses to prevent SSRF vulnerabilities.
- API2:2023 – Broken Authentication: Ensure robust authentication mechanisms (e.g., OAuth 2.0) and validate token expiration workflows.

Encryption at Rest

Sensitive data stored in databases must be encrypted at rest using industry-standard algorithms.
Validate that no sensitive data appears in logs or URLs.

2. HTTP Methods

Standard Usage

Use HTTP methods consistently:
- GET: Retrieve data without modifying server state.
- POST: Create new resources or trigger server-side operations.
- PUT: Update existing resources (use full resource payloads).
- PATCH: Partially update an existing resource.
- DELETE: Remove a resource.

Idempotency

Ensure PUT, PATCH, and DELETE methods are idempotent, meaning multiple identical requests result in the same state.

Testing HTTP Methods

Validate all HTTP methods through integration tests to ensure compliance with expected behavior.

3. Error Handling and Responses

Standardized Error Format

All APIs must return errors in a standardized format. Example:

{
  "error": "invalid_request",
  "message": "The request is missing a required parameter.",
  "details": [
    "Parameter 'user_id' is required."
  ]
}

Verbose Descriptions

Include human-readable error messages to help developers debug issues.
Ensure error codes and descriptions align with the OpenAPI Specification.

HTTP Status Codes

Use appropriate status codes for each operation:
- 200 OK: Successful GET, PUT, or PATCH operations.
- 201 Created: Successful POST operation resulting in a new resource.
- 204 No Content: Successful DELETE operation.
- 400 Bad Request: Invalid input or missing parameters.
- 401 Unauthorized: Authentication failure.
- 403 Forbidden: Insufficient permissions.
- 404 Not Found: Resource does not exist.
- 429 Too Many Requests: Rate limit exceeded.

Testing Error Scenarios

Validate all error scenarios to ensure proper responses and actionable error messages.
Maturity Levels:
- Foundational: Basic error handling for major scenarios.
- Growing: Detailed error messages for all endpoints.
- Scaling: Automated error validation using test tools.
- Innovating: AI-driven insights for error patterns and predictions.

4. Documentation and Developer Experience

Interactive Documentation

Generate API documentation using the OpenAPI Specification (latest supported version).
Include examples for all endpoints to demonstrate request/response workflows.
Maturity Levels:
- Foundational: Static documentation with examples.
- Growing: Interactive, auto-generated documentation.
- Scaling: Developer tools for API testing.
- Innovating: Embedded developer environments for testing.

Getting Started Section

Provide a “Getting Started” section in the documentation to guide new users through authentication, common workflows, and testing endpoints.
Use the Getting Started Guide Template as a reference.

Sandbox Environment

Offer a sandbox environment that mirrors production schemas and error codes for testing.
Validate sandbox alignment through API audit tests.

5. Naming Conventions and Standards

Resource Naming

Use descriptive, industry-standard English terms for resource names (e.g., books, users, loans).
Avoid ambiguous terms like type or status without additional context.

Attribute Naming

Use camelCase for attribute names (e.g., userId, bookTitle).
Avoid acronyms and abbreviations to ensure clarity.
Validate naming conventions during OpenAPI validation.

6. Localization and Internationalization

Accept Headers

Support localization using the Accept-Language header for API responses.
Provide localized strings and ensure all error messages can be translated.

Date and Time Formats

Use ISO 8601 format for all date and time fields, including time zones.

"createdAt": "2024-12-21T10:00:00Z"

Testing Localization

Validate localized responses and error messages through functional tests.

7. Versioning and Deprecation

Versioning Strategy

Use semantic versioning (e.g., /v1, /v2) to indicate major changes.
Avoid breaking changes within a version. Deprecate old endpoints with sufficient notice.

Deprecation Notices

Communicate deprecations through the Developer Portal and include headers in API responses:

Deprecation: true
Sunset: 2025-01-01
Link: <https://developer.portal.com/docs/deprecation>; rel="deprecation"

8. Pagination and Filtering

Pagination

Use standard pagination parameters:
- page: Current page number.
- limit: Number of items per page.

Filtering

Allow filtering by common attributes (e.g., title, author, genre):

GET /books?title=harry&author=rowling

Testing Pagination and Filtering

Validate that pagination and filtering work as expected using API test cases.
Maturity Levels:
- Foundational: Support basic pagination and filtering.
- Growing: Ensure consistent behavior across endpoints.
- Scaling: Optimize performance for large datasets.
- Innovating: Intelligent filtering and predictive query support.

9. Testing and Validation

Automated Validation

Use tools like Spectral to validate OpenAPI specifications for completeness and consistency.

Error Testing

Test error scenarios for all endpoints to ensure proper responses and actionable error messages.

OWASP Compliance Testing

Test APIs against OWASP API Security Top 10 risks:
- API6:2023 – Unrestricted Access to Sensitive Business Flows: Validate proper access restrictions.
- API7:2023 – Server-Side Request Forgery (SSRF): Validate inputs and responses to prevent SSRF vulnerabilities.
- API2:2023 – Broken Authentication: Test token expiration, refresh workflows, and error handling.

10. Refining and Validating the API Style Guide

Review and Feedback

Conduct periodic reviews of the style guide with cross-functional teams (product, engineering, compliance).
Gather feedback from API consumers to address usability concerns.

Version Control

Maintain the style guide in a version-controlled repository to track changes and ensure team alignment.

Integration with Development Workflows

Embed style guide principles into API linting tools and CI/CD pipelines.
Regularly validate OpenAPI specifications against the guide using automated tools like Spectral.