id = "api-design"
name = "API Design & Specification"
description = "Design a REST API from requirements: endpoints, request/response schemas, auth, error handling, and OpenAPI spec."
category = "engineering"
tags = ["api", "design", "openapi", "engineering"]

[i18n.zh]
name = "API 设计与规范"
description = "从需求出发设计 REST API：端点、请求/响应结构、认证、错误处理，输出 OpenAPI 规范。"

[[parameters]]
name = "requirements"
description = "Feature or product requirements the API needs to satisfy"
param_type = "string"
required = true

[[parameters]]
name = "tech_stack"
description = "Technology stack and any existing API conventions"
param_type = "string"
required = false
default = ""

[[steps]]
name = "resource_model"
prompt_template = """
You are an API architect. From the requirements below, identify the core resources and their relationships:
1. List every resource (noun)
2. Define attributes and types for each
3. Map relationships (one-to-many, many-to-many)
4. Identify which resources need CRUD vs. action-oriented endpoints

Requirements:
{{requirements}}

Tech stack / conventions:
{{tech_stack}}
"""

[[steps]]
name = "endpoint_design"
prompt_template = """
Design the full set of REST endpoints based on the resource model. For each endpoint specify:
- Method + path
- Path/query parameters
- Request body schema (JSON)
- Success response schema + status code
- Error responses (4xx, 5xx)
- Auth requirement
- Idempotency and side-effect notes

Resource model:
{{resource_model}}
"""
depends_on = ["resource_model"]

[[steps]]
name = "openapi_spec"
prompt_template = """
Write a complete OpenAPI 3.1 YAML specification for the API designed above. Include:
- info block with title, version, description
- All paths with operations
- Reusable schemas in components/schemas
- Security schemes
- Example request/response bodies

Endpoint design:
{{endpoint_design}}
"""
depends_on = ["endpoint_design"]