v0.5.0¶

Released: 2026-07-15

This release adds exemplar specifications, a pattern library, MCP resources for AI agents, and fix suggestions.

Highlights¶

Exemplar specifications - reference OpenAPI specs demonstrating style profile best practices
Pattern library - reusable solutions for common API design problems with examples
MCP resource handlers - AI agents can access profiles, exemplars, patterns, and rubrics
Fix suggestions - AI-powered suggestions to fix style violations with JSON Patch support

Installation¶

go install github.com/plexusone/systemspec-apistyle/cmd/api-style@v0.5.0

Upgrade from v0.4.0¶

No breaking changes. All v0.4.0 commands continue to work.

New features:

Use api-style exemplar list/show/copy to work with exemplar specs
Use api-style pattern list/show to explore design patterns
Use api-style suggest-fixes or lint --suggest-fixes for fix recommendations
MCP resources available for AI agent integration

Features¶

Exemplar Specifications¶

Exemplars are reference OpenAPI specifications that demonstrate best practices for a style profile:

# List all exemplars
api-style exemplar list

# Show exemplar content
api-style exemplar show default-minimal

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

Available exemplars:

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 provide reusable solutions for common API design problems:

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

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

Available patterns:

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

Each pattern includes:

Problem description
Solution explanation
When to use
Code examples
Related rules
External references

Fix Suggestions¶

Get AI-powered suggestions to fix style violations:

# Include suggestions in lint output
api-style lint openapi.yaml --suggest-fixes

# Generate suggestions from violations file
api-style lint openapi.yaml --format json --output violations.json
api-style suggest-fixes violations.json --profile default

Suggestions include:

Recommended fix value
Reasoning for the fix
Confidence score
JSON Patch operations for automated fixing

MCP Resources¶

The MCP server now exposes 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

Use with Claude Desktop or Claude Code:

{
  "mcpServers": {
    "api-style": {
      "command": "mcp-api-style"
    }
  }
}

New CLI Commands¶

exemplar¶

Command	Description
`exemplar list`	List available exemplars
`exemplar show <name>`	Display exemplar content
`exemplar copy <name> <path>`	Copy exemplar to file

pattern¶

Command	Description
`pattern list`	List patterns for a profile
`pattern show <id>`	Display pattern details

suggest-fixes¶

Flag	Short	Default	Description
`--profile`	`-p`	`default`	Style profile
`--format`	`-f`	`text`	Output format
`--max`		`50`	Max suggestions
`--include-patch`		`true`	Include JSON Patch

lint (new flag)¶

Flag	Description
`--suggest-fixes`	Include fix suggestions in output