API Style Spec

Machine-readable API style specification format that generates human documentation, linting rules, LLM evaluation rubrics, and AI agent instructions from a single source of truth.

Overview

API style guides from Microsoft, Google, and Zalando have become industry standards, but they exist only as human-readable documents. api-style-spec creates a machine-readable specification format that serves as the canonical source, generating all artifacts from one definition.

api-style-spec (source of truth)
    ├── Human Style Guide (Markdown)
    ├── Deterministic Linters (Spectral/vacuum)
    ├── LLM Review Rubrics
    ├── AI Agent Instructions (Claude Code, Kiro)
    └── MCP Server Tools

Features

• 📋 Unified Specification - Define rules once, generate all artifacts
• ✅ Deterministic Linting - Fast, CI-friendly checks via vacuum
• 🧠 LLM Evaluation - Semantic analysis for rules that can't be linted
• 🏢 Industry Profiles - Pre-built profiles based on Microsoft, Google, Zalando guidelines
• 🏆 Conformance Levels - Graduated compliance (bronze/silver/gold)
• 🌐 Multi-Platform - CLI, Web UI, MCP server, AI agents
• 📖 Exemplar Specs - Reference OpenAPI specifications demonstrating best practices
• 🧩 Pattern Library - Reusable solutions for common API design problems
• 🔧 Fix Suggestions - AI-powered suggestions to fix style violations

Installation

go install github.com/plexusone/api-style-spec/cmd/api-style@latest

Quick Start

# Lint an OpenAPI specification
api-style lint openapi.yaml

# Lint with a specific profile
api-style lint openapi.yaml --profile azure

# Lint with fix suggestions
api-style lint openapi.yaml --suggest-fixes

# Lint multiple files with glob patterns
api-style lint api/*.yaml --recursive

# Watch mode for continuous linting
api-style lint openapi.yaml --watch

# Combined lint + LLM evaluation
api-style analyze openapi.yaml --profile azure --level silver

# Generate human-readable style guide
api-style generate guide --spec my-style.json --output docs/

# View exemplar specifications
api-style exemplar list
api-style exemplar show default-minimal
api-style exemplar copy default-minimal ./my-api.yaml

# Explore design patterns
api-style pattern list
api-style pattern show cursor-pagination

# Get fix suggestions for violations
api-style suggest-fixes violations.json --profile default

Configuration

Create .api-style.yaml in your project root:

# .api-style.yaml
profile: azure
level: silver

include:
  - "openapi.yaml"
  - "**/api.yaml"

exclude:
  - "**/generated/**"

exceptions:
  - rule: URI-001
    paths: ["/legacy/**"]
    reason: "Legacy API cannot be changed"

severity-overrides:
  URI-002: warn

See .api-style.yaml.example for a complete example.

Specification Format

{
  "$schema": "https://api-style-spec.dev/schema/v1/api-style-spec.schema.json",
  "version": "1.0.0",
  "name": "my-api-style",
  "extends": ["default"],

  "rules": [
    {
      "id": "URI-001",
      "title": "Use plural resource names",
      "category": "uri-design",
      "severity": "error",
      "rationale": "Plural resources improve consistency.",
      "examples": {
        "good": ["/users", "/orders"],
        "bad": ["/user", "/order"]
      },
      "enforcement": {
        "type": "spectral",
        "function": "pattern",
        "options": {"match": "^/[a-z]+s(/|$)"}
      }
    }
  ]
}

CLI Commands

Command	Description
api-style lint	Deterministic linting (supports glob patterns, --watch, --recursive, --suggest-fixes)
api-style evaluate	LLM-based evaluation
api-style analyze	Combined lint + evaluate
api-style suggest-fixes	Generate fix suggestions for violations
api-style exemplar list	List available exemplar specifications
api-style exemplar show	Display an exemplar specification
api-style exemplar copy	Copy an exemplar to a local file
api-style pattern list	List available design patterns
api-style pattern show	Display pattern details with examples
api-style score-profile	Score a style profile using LLM evaluation
api-style generate guide	Generate Markdown documentation
api-style generate mkdocs	Generate MkDocs multi-page site
api-style generate spectral	Generate Spectral ruleset
api-style generate rubric	Generate LLM evaluation rubric
api-style hooks	Generate AI assistant hooks
api-style hooks init	Install git pre-commit hook
api-style diff	Breaking change detection
api-style serve mcp	Start MCP server
api-style serve web	Start Web UI

Built-in Profiles

Profile	Rules	Categories	Focus
default	106	27	Industry-leading, SDK-optimized (ogen)
comprehensive	88	26	Full coverage, all best practices
zalando	147	13	E-commerce, events
microsoft-rest	123	15	Enterprise REST APIs
microsoft-graph	82	12	OData/Graph APIs
azure	23	9	Azure cloud services
google	20	7	Resource-oriented design
minimal	29	7	Basic API hygiene

Default Profile Highlights:

• 100% evaluable with LLM-as-Judge criteria
• 34% deterministic Spectral enforcement
• SDK-optimized for ogen, openapi-generator
• Multi-tenancy patterns with ~ alias
• RFC 9457 Problem Details for errors
• Discriminated unions for polymorphism

Exemplar Specifications

Exemplars are reference OpenAPI specifications that demonstrate best practices for a style profile. Use them as starting points or learning resources.

# List all exemplars
api-style exemplar list

# Show a specific exemplar
api-style exemplar show default-minimal

# Copy to local file as starting point
api-style exemplar copy default-minimal ./my-api.yaml

Exemplar	Profile	Description
default-minimal	default	Minimal CRUD API demonstrating core patterns
default-comprehensive	default	Full-featured API with pagination, errors, versioning

Pattern Library

Design patterns are reusable solutions to common API design problems. Each pattern includes problem/solution descriptions, code examples, and related rules.

# List patterns for a profile
api-style pattern list --profile default

# Show pattern details
api-style pattern show cursor-pagination

Pattern	Category	Description
cursor-pagination	pagination	Cursor-based pagination for large datasets
rfc9457-errors	errors	RFC 9457 Problem Details for error responses
discriminated-unions	schemas	Type-safe polymorphism with discriminator fields

MCP Server Resources

The MCP server exposes API style resources for AI agents:

Resource URI	Description
apistyle://profiles	List available profiles
apistyle://profile/{name}	Get profile specification
apistyle://exemplars	List available exemplars
apistyle://exemplar/{name}	Get exemplar content
apistyle://patterns/{profile}	List patterns for a profile
apistyle://pattern/{profile}/{id}	Get pattern definition
apistyle://rubric/{profile}/{mode}	Get evaluation/generation rubric

AI Agent Integration

api-style-spec integrates with AI assistants for automated API design:

# Generate Claude Code hooks
api-style hooks --format claude-code > .claude/CLAUDE.md

# Install as pre-commit hook
api-style hooks init

# Start MCP server for AI agents
api-style serve mcp

AI agents can use MCP resources to:

• Access style profiles and rules during API generation
• Retrieve exemplar specs as reference implementations
• Look up design patterns for specific problems
• Get structured rubrics for self-evaluation

Documentation

• Getting Started
• Automated API Governance - AI-first API design workflow
• CI/CD Integration - Pipeline integration and pre-commit hooks
• Documentation Generation - Generate Markdown and MkDocs sites
• Creating Custom Profiles
• Writing Custom Rules
• MRD | PRD | TRD | Roadmap

Related Projects

• vacuum - Fast OpenAPI linter (used internally)
• structured-evaluation - LLM evaluation framework
• multi-agent-spec - Agent definitions
• assistantkit - AI assistant file generation

License

MIT