Menu
API-first design patterns — OpenAPI, REST conventions, error models, versioning
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when creating an SDD implementation plan from exploration.md, with deep interview, task breakdown, and batch assignments.
Generate a Product Requirements Document via interactive interview. Writes a markdown PRD that captures intent, user stories, and out-of-scope. Use when the brief is vague, when no ticket is bound, or when SDD invokes it from its PRD gate.
Use when executing an SDD plan via batch-based task implementation, tracking progress with [ ]/[X] markers and quality gates.
Use when starting an SDD workflow to discover codebase context, curate relevant files, and prepare exploration.md for planning.
SDD Orchestrator coordinates SDD (Spec-Driven Development) workflow via sub-agents
Use when reviewing code changes before commit, comparing implementation against SDD plan, or doing standalone code review with advisor consultation.
| name | api-first-advisor |
| scope | ["backend","api"] |
| description | API-first design patterns — OpenAPI, REST conventions, error models, versioning |
| version | 1.0 |
| tags | ["api","openapi","rest","http","versioning","error-handling"] |
Guide API design using an API-first approach: define the contract in OpenAPI before writing implementation code. Apply consistent REST conventions, proper HTTP semantics, RFC 7807 error models, and versioning strategies.
Design the API contract before implementation. The OpenAPI specification is the source of truth; code is generated from or validated against it. This enables frontend and backend teams to work in parallel, contract tests before implementation, and breaking changes visible in spec diffs.
# Avoid: verb-based paths
POST /createOrder
GET /getOrderById?id=123
# Prefer: noun-based with HTTP method as the verb
POST /orders
GET /orders/{orderId}
DELETE /orders/{orderId}
POST /orders/{orderId}/cancellations <- sub-resource for actions
/orders <- collection
/orders/{id} <- item
/products
/customers
/customers/{customerId}/orders
/orders/{orderId}/items
/orders/{orderId}/items/{itemId}
Keep nesting to 2 levels maximum. Deep nesting becomes hard to maintain.
GET /orders?status=pending&customerId=c-123
GET /products?sort=price&direction=asc
GET /orders?page=2&pageSize=25
"placedAt": "2026-03-22T14:30:00Z"Location header on 201 Created responsesdata field with pagination metadataDetailed patterns and examples are available in the references/ directory. Load these on demand when the review touches the specific topic.
references/openapi-guide.md for OpenAPI 3.1 specification structure, reusable schemas, and spec authoring patterns.references/error-model.md for RFC 7807 Problem Details format, field definitions, and domain-specific error extension examples.references/versioning.md for URL path versioning, header versioning, and deprecation policy with Sunset headers.Before finalizing your review, check gotchas.md for common Claude mistakes in this domain.
Location header returned on 201 Created responsesSunset and Deprecation headersThis skill supports advisor mode: when invoked by the SDD orchestrator with a GUIDANCE CONTEXT FROM PLANNER block in the prompt, use the following procedure instead of the standard interactive review flow.
Advisor mode is active when the prompt contains:
GUIDANCE CONTEXT FROM PLANNER: blockCURRENT PLAN EXCERPT: blockGUIDANCE CONTEXT FROM PLANNER block to understand what the planner needs reviewed.CURRENT PLAN EXCERPT to see the specific tasks and design decisions.Focus ONLY on your specialist domain: REST conventions, OpenAPI spec quality, error models, versioning.
### Strengths
- [What looks sound in the plan from this skill's domain perspective]
### Issues Found
[Severity: Critical / Major / Minor — reference specific task IDs or section names]
- T001: [issue description]
### Recommendations
[Specific, actionable. Reference task ID or section name for each recommendation.]
- T001: [recommendation]
Save full advice output to engram:
mem_save(
title: "sdd/{change-name}/guidance/api-first-advisor",
type: "architecture",
project: "{project-name}",
content: "{your full structured advice output}"
)
If engram is unavailable, skip silently.
Return a concise summary (3-5 bullet points) plus the engram observation ID:
### Summary
- [key point 1]
- [key point 2]
- ...
### Engram ID
{observation_id or "unavailable"}
Do NOT return an SDD Envelope when in advisor mode.