API Specification - Standards & Guidelines

Standard conventions, guidelines, and best practices for API specifications

🟡 STANDARD RULES

Operation Naming Conventions

Use ONLY these prefixes:

Forbidden prefixes: describe, fetch, retrieve, find, query, add, remove, modify, patch

Descriptions - Always From Documentation

MANDATORY: When creating/updating specs:

1. Check vendor documentation for operation descriptions
2. Include descriptions when available
3. Copy accurately from official documentation

paths:
  /users/{userId}:
    get:
      operationId: getUser
      summary: Retrieve a user
      description: |
        Returns detailed information about a specific user including
        their profile, permissions, and account status.
      parameters:
        - name: userId
          description: The unique identifier of the user
          required: true

When descriptions are not available:

• Create minimal factual description
• Document the gap

Schema Organization

Model Definition Source Priority:

1. Official Documentation - Definitive source, include ALL documented fields
2. API Responses - Only when significantly mismatches docs
3. Field Inclusion - Include ALL documented fields (may be optional)

Schema Naming Patterns:

User              # Main resource
UserInfo          # Extended version
UserBase          # Minimal version
UserCreateInput   # Create request
UserUpdateInput   # Update request
UserSummary       # Abbreviated (for nested usage)

Parameter Naming - Avoid Conflicts

Shared parameters MUST include operation name to avoid conflicts:

# ❌ WRONG - Generic name, could conflict
components:
  parameters:
    withPictureParam:  # Used by multiple operations
      name: withPicture
      in: query

# ✅ CORRECT - Operation-specific name
components:
  parameters:
    withPictureListUsersParam:  # Specific to listUsers
      name: withPicture
      in: query
    withPictureGetUserParam:    # Specific to getUser
      name: withPicture
      in: query

Rule: Parameter component name = {paramName}{OperationName}Param

Enum Descriptions - x-enum-descriptions

ALL enum values MUST have x-enum-descriptions:

# ❌ WRONG - Enums without x-enum-descriptions
status:
  type: string
  enum: [A, I, S]
  description: User status

# ❌ WRONG - Even clear enums need descriptions
type:
  type: string
  enum: [active, inactive, pending]
  description: Account type

# ✅ CORRECT - x-enum-descriptions for all enums
status:
  type: string
  description: Current status of the user account
  enum: [A, I, S]
  x-enum-descriptions:
    - Active - user can access the system
    - Inactive - user account is deactivated
    - Suspended - user access is temporarily disabled
  example: A

# ✅ CORRECT - Even for clear values
type:
  type: string
  description: Type of the account
  enum: [active, inactive, pending]
  x-enum-descriptions:
    - Account is active and can be used
    - Account is deactivated and cannot be used
    - Account is awaiting activation
  example: active

WHY: x-enum-descriptions provide context and clarity for ALL enum values, not just abbreviated ones. They help users understand the exact meaning and implications of each value.

🟢 GUIDELINES

Security Schemes

• ALWAYS use OAuth2 type with scopes
• Even for API Key/PAT/Basic Auth, define as OAuth2
• Scopes define required permissions per operation

components:
  securitySchemes:
    bearerAuth:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            user:read: Read user information
            user:write: Modify user information

API Metadata Configuration

x-impl-name Format:

• MUST be single PascalCase identifier (no spaces)
• Use service brand name as-is (preserve capitalization)
• For multi-word names: combine using PascalCase

# ✅ CORRECT
x-impl-name: GitHub
x-impl-name: AccessManagement      # Multi-word: "Access Management" → AccessManagement
x-impl-name: AmazonS3

# ❌ WRONG
x-impl-name: Access Management     # Has space (should be AccessManagement)
x-impl-name: github                # Not PascalCase
x-impl-name: GitHub API            # Multiple words with space

WHY: Combine multi-word names into single PascalCase identifier while preserving brand capitalization.

Other Metadata:

• Do NOT set title, description, or version (sync-meta script handles)
• Configure server base URL from service configuration

Schema Validation

• Run npx swagger-cli validate api.yml after any changes
• Specification must validate without errors
• Fix all validation errors before proceeding

Validation Quick Reference

Failure Recovery

If ANY rule is violated:

1. STOP all work immediately
2. Document the violation
3. Fix the violation
4. Re-validate ALL rules
5. Only proceed when 100% compliant

Resource Scope - Check Product Documentation

ALWAYS check if resources belong to a parent entity (organization, workspace, project):

# ❌ WRONG - Missing parent scope
/users:
  get:
    operationId: listUsers

# ✅ CORRECT - Scoped to organization
/organizations/{organizationId}/users:
  get:
    operationId: listUsers
    parameters:
      - name: organizationId
        in: path
        required: true

How to determine scope:

1. Check product documentation for resource hierarchy
2. Look for mentions of "organization", "workspace", "project", "team"
3. If resources belong to parent entity → include in path
4. If resources are truly global → root path is OK

Common parent scopes:

• /organizations/{organizationId}/...
• /workspaces/{workspaceId}/...
• /projects/{projectId}/...
• /teams/{teamId}/...

Best Practices

Documentation Quality

• Include operation summaries
• Add parameter descriptions
• Document ALL enum values with x-enum-descriptions
• Explain complex schemas
• Link to vendor documentation

Maintainability

• Use $ref for reusable components
• Keep schemas focused (single responsibility)
• Separate read/write schemas when needed
• Version schemas carefully
• Document breaking changes

Type Safety

• Use specific types (not just "object")
• Define formats (date-time, email, uri)
• Set minimum/maximum constraints
• Use enums for fixed values
• Mark required fields explicitly

Remember

These standards ensure:

• Consistent API design across all modules
• Clean code generation
• Type-safe implementations
• Maintainable specifications
• Framework compatibility

Follow these standards for professional, maintainable API specifications.