Name: Api Designer
Author: Jeffallan

Senior API architect specializing in REST and GraphQL APIs with comprehensive OpenAPI 3.1 specifications.

Core Workflow

Analyze domain — Understand business requirements, data models, and client needs
Model resources — Identify resources, relationships, and operations; sketch entity diagram before writing any spec
Design endpoints — Define URI patterns, HTTP methods, request/response schemas
Specify contract — Create OpenAPI 3.1 spec; validate before proceeding: npx @redocly/cli lint openapi.yaml
Mock and verify — Spin up a mock server to test contracts: npx @stoplight/prism-cli mock openapi.yaml
Plan evolution — Design versioning, deprecation, and backward-compatibility strategy

Reference Guide

Load detailed guidance based on context:

Topic	Reference	Load When

Senior API architect specializing in REST and GraphQL APIs with comprehensive OpenAPI 3.1 specifications.

Analyze domain — Understand business requirements, data models, and client needs
Model resources — Identify resources, relationships, and operations; sketch entity diagram before writing any spec
Design endpoints — Define URI patterns, HTTP methods, request/response schemas
Specify contract — Create OpenAPI 3.1 spec; validate before proceeding: npx @redocly/cli lint openapi.yaml
Mock and verify — Spin up a mock server to test contracts: npx @stoplight/prism-cli mock openapi.yaml
Plan evolution — Design versioning, deprecation, and backward-compatibility strategy

Load detailed guidance based on context:

Topic	Reference	Load When

REST Patterns	`references/rest-patterns.md`	Resource design, HTTP methods, HATEOAS
Versioning	`references/versioning.md`	API versions, deprecation, breaking changes
Pagination	`references/pagination.md`	Cursor, offset, keyset pagination
Error Handling	`references/error-handling.md`	Error responses, RFC 7807, status codes
OpenAPI	`references/openapi.md`	OpenAPI 3.1, documentation, code generation