API Design Principle (ADP) Documentation

This repository contains the documentation for API Design Principles (ADP), a comprehensive guide for designing and implementing APIs. It also deploys a Redocly ruleset as api-design-principle-beta/recommended.

Overview

The ADP documentation, built using VitePress, provides guidelines, best practices, and standards for API design across various categories. It aims to ensure consistency and quality in API development throughout the organization.

Key Features

• Comprehensive API design principles
• Multilingual support (English and Traditional Chinese)
• Semantic versioning
• OpenAPI examples
• Developer experience focus

Structure

The documentation is organized into several categories, including:

• ADP Overview
• Engineering Principles
• HTTP Basics
• REST Basics
• HTTP Semantics
• OpenAPI Design
• Error Design
• Event Design
• API Governance

Redocly Ruleset Usage

Installation

Install dependencies:

npm install -g @redocly/cli
npm add -D @redocly/openapi-core
npm add -D api-design-principle-beta

Configuration

Add .redocly.yaml to your API repo:

apiDefinitions:
  main: openapi.yaml
extends:
  - 'recommended'
  - 'api-design-principle-beta/recommended'
plugins:
  - ./node_modules/api-design-principle-beta/dist/plugin.cjs

Usage

Run with Redocly:

redocly lint

New Redocly Rules

The package includes several custom rules to enforce best practices:

• api-design-principle-beta/always-return-json-object: Ensures top-level JSON responses are objects.
• api-design-principle-beta/format-enumeration-upper-snake-case: Enforces upper snake case for enum values.
• api-design-principle-beta/no-request-body-in-get-method: Prohibits request bodies in GET methods.
• api-design-principle-beta/not-use-null-for-empty-array: Discourages null for empty arrays.
• api-design-principle-beta/no-basic-auth-in-security-schemes: Prevents basic authentication in security schemes.
• api-design-principle-beta/use-absolute-profile-url: Enforces absolute URLs for profiles.
• api-design-principle-beta/use-camel-case-for-property-name: Encourages camel case for property names.
• api-design-principle-beta/use-camel-case-for-query-parameter: Enforces camel case for query parameters.
• api-design-principle-beta/use-common-date-and-time-format: Ensures common date and time formats.
• api-design-principle-beta/use-extensible-enum: Promotes extensible enums.
• api-design-principle-beta/use-kebab-case-for-path-parameter: Enforces kebab case for path parameters.
• api-design-principle-beta/use-oas-3: Requires OpenAPI Specification 3.0.0 or higher.
• api-design-principle-beta/use-string-enum: Ensures enums are represented as strings.
• api-design-principle-beta/use-tls: Enforces TLS for server URLs.
• api-design-principle-beta/check-x-audience: Validates the x-audience extension.
• api-design-principle-beta/error4xx-rfc9457: Ensures 4xx error responses comply with RFC 9457.
• api-design-principle-beta/error5xx-rfc9457: Ensures 5xx error responses comply with RFC 9457.

Contact

For questions or feedback, please contact [email protected].