Skip to content

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, Cursor)
    └── 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, MCP server, AI assistant hooks

Quick Start

Installation

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

Basic Usage

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

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

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

Built-in Profiles

Profile Based On Focus
default Common best practices General REST API design
azure Microsoft/Azure guidelines Enterprise cloud APIs
google Google API Design Guide Resource-oriented design
zalando Zalando RESTful Guidelines E-commerce APIs

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    api-style-spec                           │
├─────────────────────────────────────────────────────────────┤
│  Style Profile (JSON)                                       │
│  ├── Rules with enforcement config                          │
│  ├── LLM evaluation rubrics                                 │
│  └── Conformance levels                                     │
├─────────────────────────────────────────────────────────────┤
│  Outputs                                                    │
│  ├── Deterministic Lint (vacuum)                            │
│  ├── LLM Evaluation (Claude)                                │
│  ├── Markdown Documentation                                 │
│  ├── Spectral Ruleset                                       │
│  └── AI Agent Instructions                                  │
└─────────────────────────────────────────────────────────────┘

Next Steps