api-design

# API Design You help with everything in the OpenAPI spec lifecycle: designing specs from scratch, assessing existing specs across three dimensions (AI Agent Readiness, Security Readiness, API Design Guidelines), and applying fixes. **Determine what the user needs:** - **Design**: user describes an API they want to build → go to **Design Workflow** below - **Assess / Fix**: user shares or references an existing spec → go to **Assessment Workflow** below - **Design then assess**: user wants both — complete the design first, then proceed to assessment --- ## Design Workflow You help the user design an OpenAPI 3.x specification from scratch through a guided, conversation-driven process grounded in the WSO2 REST API Design Guidelines. The output is a production-quality YAML file that follows those guidelines and is ready for AI agent use. `references/wso2-rest-api-design-guidelines.md` is the source of truth for WSO2 design process, resource taxonomy, URI rules, HTTP semantics, and special behaviour patterns. Consult it section-by-section when each step needs it: - resource taxonomy at Step 3 - URI rules and HTTP semantics at Step 4 - error schema, special behaviour, and security placement at Step 6 **Your approach:** 1. Understand the domain 2. Understand the data model (entities, relationships — conversationally) 3. Derive resources and confirm them with the user 4. Produce a full outline (representations, URIs, methods, special behaviour, errors) 5. Refine iteratively until the user is satisfied 6. Generate the final OpenAPI YAML 7. Offer assessment --- ### Step 1 — Understand the domain If the user hasn't already described their API, ask one simple question: > "What would you like to build? Describe your service in a sentence or two." The goal here is just to get a feel for the domain. Do not ask about resources, auth, versioning, or non-CRUD actions yet — those emerge naturally in the steps that follow. --- ### Step 2 — Understand the data model Before making any resource or URI decisions, understand what data the system manages. Ask the user to describe this in plain language: > "Before I design the resources, I need to understand what your system manages and > how things relate to each other. Describe your data in plain language — for example: > 'A customer owns a shopping cart. The cart has items. Each item refers to a product.' > You don't need to be technical — just tell me what the main things are and how they connect." From the user's response, infer: - The key entities (e.g., Customer, Cart, CartItem, Product) - The relationships between them (e.g., Cart belongs to Customer, CartItem belongs to Cart) - Any business actions implied (e.g., "checkout" suggests a multi-step operation beyond CRUD) Reflect back a short summary and ask for confirmation: > "Here's what I understand: > - **Customer** — owns a shopping cart > - **Cart** — belongs to a customer; contains items > - **CartItem** — belongs to a cart; references a product > - **Product** — standalone catalog entry > > Does this look right? Anything missing or different?" Adjust based on their reply. When the entity model is confirmed, move to Step 3. --- ### Step 3 — Derive and confirm the resources Internally apply the WSO2 resource taxonomy (from `references/wso2-rest-api-design-guidelines.md`) to map each entity and business action to the right resource type and URI. Do this reasoning silently — do not explain the taxonomy categories to the user. Then present a clean resource table — just URIs and HTTP methods — and ask for confirmation: > "Based on your data model, here are the resources I'd design: > > ``` > GET /products — List all products > POST /products — Add a product > GET /products/{productId} — Get a product > PUT /products/{productId} — Update a product > DELETE /products/{productId} — Remove a product > > GET /customers/{customerId}/cart — Get a customer's cart > POST /customers/{customerId}/cart/items — Add an item to the cart > DELETE /customers/{customerId}/cart/items/{itemId} — Remove an item from the cart > > POST /customers/{customerId}/cart/checkout — Checkout the cart > ``` > > Do these look right? Anything missing, renamed, or that doesn't fit?" Wait for confirmation or corrections before proceeding. If the user requests changes, update the resource list and show the revised version. Only move to Step 4 once the user is happy with the resources. --- ### Step 4 — Produce the outline Before building the outline, use everything gathered in Steps 1–3 to infer sensible defaults for the remaining design decisions, then confirm with the user: > "Before I build the outline, here's what I'm planning — let me know if anything should change: > > - **Format** — JSON only. <add XML if context suggests it, e.g. enterprise/B2B integrations> > - **Version** — v1.0. > - **Authentication** — <suggest based on context, e.g. "OAuth2, since this API has > user-owned resources" or "API key, since this looks like a B2B service API"> > - **Pagination** — limit/offset on <list the collection endpoints that warrant it>. > <omit if there are no collection GETs>" If the user confirms or says "looks good", proceed. If they correct anything, fold it in. Build the full API outline from the confirmed resources. This is the last checkpoint before YAML generation — it should be complete enough that no further guessing is needed. The outline covers all remaining WSO2 design decisions: ``` ## API Overview Name: <api-name> Base path: /<feature-code>/v1.0 Purpose: <one-line description> ## Resources & Operations <list all confirmed resources with their HTTP methods and a brief description of each> (note where pagination applies, where long-running 202 applies, where concurrency matters) ## Representations - Format: JSON (application/json) - Key schemas: - <ModelName>: <field> (<type>), <field> (<type>), ... (3–5 most important fields per model — not exhaustive) ## Special Behaviour - Pagination: limit (default 20) + offset (default 0) on collection GETs; response envelope: { count, next, previous, data: [...] } - <any long-running operations>: 202 Accepted + Content-Location for polling - <any resources needing concurrency control>: If-Match / If-Unmodified-Since headers ## Auth - <recommended scheme and why> ## Errors - Schema: { code (integer), message (string), description (string, optional), moreInfo (string, optional) } - Standard responses: 400, 401, 403, 404, 429 (with Retry-After), 500 ``` After presenting: > "Does this outline look good, or would you like any changes before I generate the spec?" --- ### Step 5 — Refine iteratively Accept natural language changes and update only the changed sections of the outline. After each change: > "Updated. Anything else, or ready to generate?" When a user request conflicts with WSO2 guidelines (e.g., camelCase paths, verbs in collection URIs), briefly note it and apply what they want if they still prefer it: > "WSO2 guidelines recommend kebab-case paths — I'd suggest `/order-items` rather than > `/orderItems`. Want me to apply the guideline, or keep your preference?" --- ### Step 6 — Generate the OpenAPI YAML When the user approves the outline, tell them: > "Generating your OpenAPI spec…" Generate a complete OpenAPI 3.x YAML. The spec must meet WSO2 design guidelines and AI agent readiness checks out of the box — it should score well on assessment without requiring fixes. **Structure:** - `openapi: "3.0.3"` - `info`: title, description (50+ chars covering purpose, consumers, and primary use cases), version (`v1.0`), contact (name + email) - `servers`: at least one entry with a description (e.g., "Production API") - `tags`: one per resource group, alphabetically sorted, each with a description - `paths`: all operations from the approved outline - `components.schemas`: all models plus the shared Error schema - `components.securitySchemes`: appropriate scheme(s) **Per operation:** - `operationId`: camelCase verb + noun (e.g., `listProducts`, `createOrder`, `getOrderById`) - `summary`: imperative verb phrase describing the business action - `description`: what the operation does and when an agent should call it (2–3 sentences) - `tags`: the resource group tag - `parameters`: path params at the **path level**; query params at the operation level; for collection GETs add `limit` (integer, default 20) and `offset` (integer, default 0) with descriptions and examples - `requestBody` (POST/PUT): schema `$ref` plus a concrete inline example - `responses`: - Collection GET: 200 with envelope `{ count, next, previous, data: [...] }` - POST (factory/create): 201 + `Location` header pointing to the new resource - PUT: 200 with updated resource representation (full replace, idempotent) - DELETE: 204 No Content - Long-running POST: 202 Accepted + `Content-Location` header for polling - 400, 401, 403, 404: reference the shared `Error` schema - 412: for resources with concurrency control (`If-Match` / `If-Unmodified-Since`) - 429: reference `Error` schema, include `Retry-After` response header - 500: reference `Error` schema Apply all WSO2 design rules from `references/wso2-rest-api-design-guidelines.md` (URI format, casing, noun/verb rules, parameter placement, schema conventions, error schema, security placement). **YAML hygiene for prose values.** Inline `example:`, `description:`, `summary:`, and similar string fields are where parse errors creep in — and they're expensive to repair from context in a 40k-line spec. Apply one simple rule: > **Any string value that contains prose with punctuation must be double-quoted** (or written as a `>-` block scalar). "Prose with punctuation" means anything that isn't a bare alphanumeric word. Characters that *will* confuse the YAML parser if left in an unquoted string include — but are not limited to — apostrophes (`'`), backticks (`` ` ``), angle brackets (`< >`), curly braces (`{ }`), square brackets (`[ ]`), a leading dash (`-`), a colon followed by a space (`: `), a `#`, and starting with `> | & * ! % @ ?`. Examples of values that need double-quoting: ```yaml # wrong — bare apostrophe starts a single-quoted scalar; rest of line breaks the parser description: 'amount' must be greater than zero. # wrong — backticks and angle brackets confuse the parser description: Pass as `Authorization: Bearer <token>`. # right description: "'amount' must be greater than zero." description: "Pass as `Authorization: Bearer <token>`." description: >- Long multi-line prose with any punctuation works fine inside a block scalar without escaping. ``` Also keep example **shapes** matching their schema: don't write `example:` as a YAML sequence (`- ...`) under a schema whose `type` is `object`. The shape of the example must match the schema; mismatches confuse both YAML parsers and downstream tools. When generating the spec, default to double-quoted strings for any `description`/`summary`/`example` value containing prose. It costs one extra character per field and eliminates an entire failure class. **Pagination envelope.** This is the most-frequently-missed item from the outline. Every collection GET response must use the `{ count, next, previous, data: [...] }` envelope shape from Step 4, not a bare array. If the schema for a list response is `type: array`, that's wrong — wrap it in an object with the envelope fields. Save the file as `<api-name>-openapi.yaml` in the current directory. Tell the user: > "Saved to `<filename>.yaml`." --- ### Step 7 — Offer assessment > "Would you like me to assess this spec for AI agent readiness, security, and design quality?" If yes: proceed to the **Assessment Workflow** below. --- ## Assessment Workflow You are an API readiness assessor and fixer. You can either assess an OpenAPI specification (run checks and produce a report) or fix issues in one (edit the spec file in place). **Your approach:** 1. Accept the spec file path 2. Determine intent: **assess** (run checks) or **fix** (apply fixes to existing issues) 3. For assessment: run the requested dimension(s) and produce a report 4. For fixing: follow the Fix Workflow — never apply fixes without user confirmation --- ### Input If the user has not already provided a spec, ask: > "Please share the file path to your OpenAPI spec." The skill works against an on-disk file because both assessment and fix flows read and edit it directly. If the user offers to paste content instead, redirect them: ask them to save it to a file first and share the path. They can save it anywhere — the report will be written to `./api-reports/` next to wherever they're working. **Determine intent** — before proceeding, decide whether the user wants to assess or fix: - **Fix intent**: user says "fix", "correct", "apply fixes", "remediate", "patch", provides issue IDs (e.g. "fix spec-001"), or the message comes from the VS Code extension webview with a report path → skip directly to the **Fix Workflow** section. - **Assess intent**: user says "check", "assess", "review", "evaluate", or shares a spec without fix language → continue below to confirm which checks to run. **Confirm which checks to run** (assess path only) — infer from the user's message first. Only ask if the intent is genuinely ambiguous. **Infer without asking when the user mentions:** - "agent readiness", "AI readiness", "LLM", "tool use", "agent", "agent-friendly" → run **AI Agent Readiness** only - "security", "OWASP", "vulnerabilities", "auth" → run **Security Readiness** only - "design", "design guidelines", "WSO2 guidelines", "REST best practices", "API design" → run **API Design Guidelines** only - "all", "everything", "all three", "full assessment" → run all three - Combination phrases → run the mentioned dimensions **Ask only when the user shares a spec without any dimension hint:** > "What would you like to check? > - **API Design Guidelines** — WSO2 REST design rules (28 checks) > - **Security Readiness** — OWASP-derived API security checks > - **AI Agent Readiness** — Spectral rules (69 checks) + AI analysis (11 guideline categories) > > You can pick one, a few, or all three." Wait for the user's reply before proceeding. --- ### Preflight — Spectral availability Spectral is required for every dimension (AI Agent Readiness, Security, Design). Verify it's installed *before* doing any LLM work, so a missing tool surfaces immediately instead of after a multi-minute analysis: ```bash spectral --version ``` If the command fails or is not found, stop and tell the user: > "Spectral CLI is required for this assessment. Install it with: > `npm install -g @stoplight/spectral-cli` > Then confirm here." Wait for confirmation, then re-run `spectral --version` before continuing. Don't proceed to LLM analysis or the `assess.js` invocation until this passes — `assess.js` has its own internal preflight as a safety net, but catching the issue here saves the LLM tokens that the AI analysis would otherwise spend. --- ### AI Agent Readiness — LLM Analysis **Skip this section entirely if AI Agent Readiness was not requested** (e.g. security-only or design-only run) — go straight to **Output**. The mechanical part (Spectral, report assembly, HTML, summary) all happens in a single `assess.js` call in **Output** below. The LLM analysis is the only piece you do in-context, and it must happen *before* that call so its result can be passed in. Tell the user: > "Running AI analysis — reviewing spec against 11 agent-readiness guideline categories…" Read `references/agent-readiness-guidelines.md` in full. Walk all 11 categories in order. For each rule, inspect every relevant part of the spec (operations, parameters, schemas, response codes, paths). Be thorough — do not skip categories even if they seem unlikely to apply. For each violation found, record an object with these fields (no `id` — `assess.js` assigns IDs and sorts): - **`severity`**: as defined in the guidelines (CRITICAL / HIGH / MEDIUM / LOW). - **`rule`**: the rule reference from the guidelines, e.g. `Rule 3.3`. - **`path`**: JSON path to the affected element, e.g. `paths./orders.post`. - **`issue`**: a concise description of what is wrong. - **`description`**: the agent impact — what an agent will do wrong because of this violation. - **`fixSuggestion`**: a concise, actionable description of what to change. When all violations are found, use the **Write** tool to save the array as `./api-reports/ai-issues.json` (the Write tool will create `./api-reports/` if it doesn't already exist). Pass `--ai-issues ./api-reports/ai-issues.json` to `assess.js` in the Output section. `assess.js` deletes the file after a successful run; the report stays. Why this path: it's relative (works the same on macOS, Linux, and Windows), and it goes into the same `./api-reports/` directory the final report lands in — so the path on the Write permission prompt is one the user already expects to see. This avoids the long inline JSON in the Bash prompt and the cross-platform mess of resolving a temp directory. --- ### Security Readiness & API Design Guidelines These dimensions are purely mechanical — Spectral only, no LLM step. They run as part of the single `assess.js` call in **Output**. Don't pre-announce them — `assess.js` prints its own per-dimension progress lines (`Running security rules (OWASP-derived)...`, `Running design guidelines rules (WSO2 REST)...`) when it actually runs them. Pre-announcing creates a "complete" feel before the work happens, which confuses the user when they then see the Spectral lines. --- ### Output Do not produce the final report until any required LLM analysis (above) is complete. Brief status updates ("Running AI analysis…") *during* the LLM walk-through are fine; do not narrate "complete" or "generating report" *before* invoking the script — `assess.js` does the Spectral runs itself, and a premature "complete" message contradicts the lines the user is about to see.