Name: spec-api
Author: engineers-hub-ltd-in-house-project

Prompt file imported from engineers-hub-ltd-in-house-project/kiro-sdd (.claude/commands/kiro/spec-api.md). Fill in {{arguments}} before use. Copyright stays with the author.

API Specification Design

Parse Arguments and Determine API Type

Feature and API type from arguments: {{arguments}}

Expected formats:

feature-name (defaults to REST)
feature-name --type rest
feature-name --type grpc
feature-name --type graphql

Instructions:

Parse {{arguments}} to extract feature name and API type
If --type flag is present, use the specified type (rest/grpc/graphql)
If no --type flag, default to REST
Generate appropriate API specification based on the selected type

Context Validation

Previous Phases Check

Use cases: @.kiro/specs/{{arguments}}/usecase.md
Sequence diagrams: @.kiro/specs/{{arguments}}/sequence.md
Database schema: @.kiro/specs/{{arguments}}/schema.md
Spec metadata: @.kiro/specs/{{arguments}}/spec.json

CRITICAL: API design requires approved schema and sequence diagrams.

Interactive Approval

Before generating API spec, ask the user:

Ready to generate [API_TYPE] API specification for [FEATURE_NAME]?
Database schema should be reviewed first.
Have you reviewed schema.md? [y/N]:

Note: Replace [API_TYPE] with the detected type and [FEATURE_NAME] with the extracted feature name.

If 'N': Stop and request review of schema first. If 'y': Update spec.json to mark schema as approved and proceed:

{
  "approvals": {
    "schema": {
      "generated": true,
      "approved": true
    }
  }
}

Task: Generate API Specification

Based on the detected API type, generate the appropriate specification:

For REST API (default or --type rest)

Generate api.md with complete OpenAPI 3.0 specification:

1. REST API Document Structure

# API Specification: [Feature Name]

## Overview
RESTful API design based on sequence diagrams and database schema.

## API Design Principles
- RESTful: Follow REST conventions
- Consistent: Uniform response format
- Versioned: API versioning strategy
- Documented: OpenAPI 3.0 specification
- Secure: Authentication and authorization

## Base Configuration

### Base URL

Development: http://localhost:8080/api/v1 Staging: https://staging.example.com/api/v1 Environment variable: https://{env}.example.com/api/v1


### Authentication
```yaml
securitySchemes:
  bearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Common Headers

headers:
  X-Request-ID:
    description: Unique request identifier for tracing
    schema:
      type: string
      format: uuid
  X-Client-Version:
    description: Client application version
    schema:
      type: string

API Endpoints

Analytics Overview

/analytics/overview:
  get:
    summary: Get analytics overview
    operationId: getAnalyticsOverview
    tags:
      - Analytics
    security:
      - bearerAuth: []
    parameters:
      - name: start_date
        in: query
        required: false
        schema:
          type: string
          format: date-time
          example: "2025-01-01T00:00:00Z"
        description: Start date for analytics period (ISO 8601)
      - name: end_date
        in: query
        required: false
        schema:
          type: string
          format: date-time
          example: "2025-01-31T23:59:59Z"
        description: End date for analytics period (ISO 8601)
    responses:
      200:
        description: Analytics overview retrieved successfully
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsOverview'
            example:
              total_sent: 10000
              total_delivered: 9500
              open_rate: 25.5
              click_rate: 3.2
              bounce_rate: 5.0
              period:
                start: "2025-01-01T00:00:00Z"
                end: "2025-01-31T23:59:59Z"
      400:
        description: Invalid request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ErrorResponse'
            example:
              error:
                code: "INVALID_DATE_RANGE"
                message: "End date must be after start date"
      401:
        $ref: '#/components/responses/UnauthorizedError'
      500:
        $ref: '#/components/responses/InternalServerError'

Campaign Metrics

/analytics/campaigns:
  get:
    summary: Get campaign metrics list
    operationId: getCampaignMetrics
    tags:
      - Analytics
    security:
      - bearerAuth: []
    parameters:
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: sort_by
        in: query
        schema:
          type: string
          enum: [created_at, open_rate, click_rate, sent_count]
          default: created_at
      - name: sort_order
        in: query
        schema:
          type: string
          enum: [asc, desc]
          default: desc
      - name: start_date
        in: query
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        schema:
          type: string
          format: date-time
      - name: status
        in: query
        schema:
          type: string
          enum: [draft, scheduled, sending, sent, failed]
    responses:
      200:
        description: Campaign metrics retrieved successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                campaigns:
                  type: array
                  items:
                    $ref: '#/components/schemas/CampaignMetrics'
                pagination:
                  $ref: '#/components/schemas/Pagination'
            example:
              campaigns:
                - id: "550e8400-e29b-41d4-a716-446655440000"
                  name: "January Newsletter"
                  status: "sent"
                  sent_count: 5000
                  open_rate: 28.5
                  click_rate: 4.2
                  created_at: "2025-01-15T10:00:00Z"
              pagination:
                page: 1
                per_page: 20
                total: 45
                total_pages: 3

Campaign Details

/analytics/campaigns/{campaign_id}:
  get:
    summary: Get detailed campaign analytics
    operationId: getCampaignDetails
    tags:
      - Analytics
    security:
      - bearerAuth: []
    parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    responses:
      200:
        description: Campaign details retrieved successfully
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignDetails'
      404:
        description: Campaign not found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ErrorResponse'

Time Series Data

/analytics/time-series:
  get:
    summary: Get time series analytics data
    operationId: getTimeSeries
    tags:
      - Analytics
    security:
      - bearerAuth: []
    parameters:
      - name: campaign_id
        in: query
        schema:
          type: string
          format: uuid
        description: Optional campaign filter
      - name: metric_type
        in: query
        required: true
        schema:
          type: string
          enum: [opens, clicks, bounces, unsubscribes]
      - name: aggregation
        in: query
        schema:
          type: string
          enum: [hour, day, week, month]
          default: day
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
    responses:
      200:
        description: Time series data retrieved successfully
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeSeriesData'

Export Analytics

/analytics/export:
  post:
    summary: Export analytics data
    operationId: exportAnalytics
    tags:
      - Analytics
    security:
      - bearerAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - export_type
              - format
            properties:
              export_type:
                type: string
                enum: [overview, campaigns, subscribers, events]
              format:
                type: string
                enum: [csv, xlsx, json]
              campaign_ids:
                type: array
                items:
                  type: string
                  format: uuid
              start_date:
                type: string
                format: date-time
              end_date:
                type: string
                format: date-time
              email_delivery:
                type: boolean
                default: false
                description: Send export via email for large files
    responses:
      200:
        description: Export completed immediately
        content:
          application/csv:
            schema:
              type: string
              format: binary
      202:
        description: Export queued for processing
        content:
          application/json:
            schema:
              type: object
              properties:
                export_id:
                  type: string
                  format: uuid
                status:
                  type: string
                  enum: [queued, processing]
                message:
                  type: string

Component Schemas

AnalyticsOverview

AnalyticsOverview:
  type: object
  required:
    - total_sent
    - total_delivered
    - open_rate
    - click_rate
  properties:
    total_sent:
      type: integer
      minimum: 0
    total_delivered:
      type: integer
      minimum: 0
    unique_opens:
      type: integer
      minimum: 0
    unique_clicks:
      type: integer
      minimum: 0
    open_rate:
      type: number
      format: float
      minimum: 0
      maximum: 100
    click_rate:
      type: number
      format: float
      minimum: 0
      maximum: 100
    bounce_rate:
      type: number
      format: float
      minimum: 0
      maximum: 100
    unsubscribe_rate:
      type: number
      format: float
      minimum: 0
      maximum: 100
    period:
      type: object
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time

ErrorResponse

ErrorResponse:
  type: object
  required:
    - error
  properties:
    error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
        request_id:
          type: string
          format: uuid

Pagination

Pagination:
  type: object
  required:
    - page
    - per_page
    - total
    - total_pages
  properties:
    page:
      type: integer
      minimum: 1
    per_page:
      type: integer
      minimum: 1
      maximum: 100
    total:
      type: integer
      minimum: 0
    total_pages:
      type: integer
      minimum: 0
    has_next:
      type: boolean
    has_prev:
      type: boolean

Response Examples

Success Response Pattern

{
  "data": {
    // Response payload
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-01-15T10:00:00Z"
  }
}

Error Response Pattern

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "start_date",
        "message": "Invalid date format"
      }
    ],
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Request validation failed
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_ERROR	500	Internal server error
SERVICE_UNAVAILABLE	503	Service temporarily unavailable

Rate Limiting

headers:
  X-RateLimit-Limit:
    description: Request limit per hour
    schema:
      type: integer
  X-RateLimit-Remaining:
    description: Remaining requests in current window
    schema:
      type: integer
  X-RateLimit-Reset:
    description: Time when limit resets (Unix timestamp)
    schema:
      type: integer

Versioning Strategy

URL versioning: /api/v1/, /api/v2/
Breaking changes require new version
Deprecation notice: 6 months minimum
Sunset period: 12 months after deprecation


### 2. API Design Best Practices

Ensure API follows:
- **RESTful conventions**: Proper HTTP methods and status codes
- **Consistent naming**: snake_case for JSON, kebab-case for URLs
- **Pagination**: Limit/offset or cursor-based
- **Filtering**: Query parameters for filtering
- **Sorting**: Consistent sort parameter format
- **Error handling**: Consistent error response format

### 3. Security Considerations

Include:
- **Authentication**: JWT/OAuth2 specification
- **Authorization**: Role-based access control
- **Rate limiting**: Prevent abuse
- **Input validation**: Parameter constraints
- **CORS policy**: Cross-origin configuration

### 4. Update Metadata

Update spec.json:
```json
{
  "phase": "api-defined",
  "endpoints_count": [number],
  "approvals": {
    "usecase": {
      "approved": true
    },
    "sequence": {
      "approved": true
    },
    "schema": {
      "approved": true
    },
    "api": {
      "generated": true,
      "approved": false
    }
  },
  "updated_at": "current_timestamp"
}

Instructions

Review sequence diagrams - Understand all interactions
Map to REST endpoints - Convert sequences to APIs
Define request/response - Complete payload schemas
Add all parameters - Query, path, headers
Document error cases - All possible errors
Include examples - Real request/response examples
Add rate limiting - Protect against abuse
Define security - Authentication/authorization
Ensure consistency - Naming, format, structure
Update metadata - Record completion

Generate a complete API specification that prevents integration issues by defining exact contracts upfront.

For gRPC API (--type grpc)

Generate api.md with Protocol Buffers specification:

1. gRPC API Document Structure

# gRPC API Specification: [Feature Name]

## Overview
gRPC service design based on sequence diagrams and database schema.

## Service Definition

### Proto File: [feature_name].proto

```protobuf
syntax = "proto3";

package [feature].v1;

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/wrappers.proto";

service [FeatureName]Service {
  // Service methods based on sequence diagrams
  rpc GetResource(GetResourceRequest) returns (GetResourceResponse) {
    option (google.api.http) = {
      get: "/v1/resources/{id}"
    };
  }
  
  // Streaming RPC for real-time updates
  rpc StreamUpdates(StreamRequest) returns (stream UpdateResponse);
  
  // Bidirectional streaming
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

Message Definitions

message GetResourceRequest {
  string id = 1;
  bool include_details = 2;
}

message GetResourceResponse {
  Resource resource = 1;
  google.protobuf.Timestamp retrieved_at = 2;
}

message Resource {
  string id = 1;
  string name = 2;
  Status status = 3;
  map<string, string> metadata = 4;
  repeated string tags = 5;
}

enum Status {
  STATUS_UNSPECIFIED = 0;
  STATUS_ACTIVE = 1;
  STATUS_INACTIVE = 2;
  STATUS_DELETED = 3;
}

Error Handling

message ErrorDetails {
  string code = 1;
  string message = 2;
  map<string, string> metadata = 3;
}

Service Configuration

type: google.api.Service
config_version: 3
name: [service].example.com

apis:
  - name: [feature].v1.[FeatureName]Service

authentication:
  rules:
    - selector: "*"
      requirements:
        - provider_id: bearer

http:
  rules:
    - selector: [feature].v1.[FeatureName]Service.GetResource
      get: /v1/resources/{id}


### For GraphQL API (--type graphql)

Generate api.md with GraphQL schema:

#### 1. GraphQL API Document Structure

```markdown
# GraphQL API Specification: [Feature Name]

## Overview
GraphQL schema design based on sequence diagrams and database schema.

## Schema Definition

### Type System

```graphql
schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

type Query {
  # Single resource query
  resource(id: ID!): Resource
  
  # List resources with pagination
  resources(
    first: Int
    after: String
    last: Int
    before: String
    filter: ResourceFilter
    orderBy: ResourceOrderBy
  ): ResourceConnection!
  
  # Search resources
  searchResources(
    query: String!
    limit: Int = 10
  ): [Resource!]!
}

type Mutation {
  # Create resource
  createResource(input: CreateResourceInput!): CreateResourcePayload!
  
  # Update resource
  updateResource(id: ID!, input: UpdateResourceInput!): UpdateResourcePayload!
  
  # Delete resource
  deleteResource(id: ID!): DeleteResourcePayload!
}

type Subscription {
  # Subscribe to resource changes
  resourceUpdated(id: ID!): Resource!
  
  # Subscribe to all changes
  allResourcesUpdated(filter: ResourceFilter): Resource!
}

Object Types

type Resource {
  id: ID!
  name: String!
  description: String
  status: ResourceStatus!
  createdAt: DateTime!
  updatedAt: DateTime!
  createdBy: User!
  metadata: JSON
  tags: [String!]!
}

type User {
  id: ID!
  email: String!
  name: String!
  resources: [Resource!]!
}

enum ResourceStatus {
  DRAFT
  ACTIVE
  ARCHIVED
  DELETED
}

Input Types

input CreateResourceInput {
  name: String!
  description: String
  status: ResourceStatus = DRAFT
  metadata: JSON
  tags: [String!]
}

input UpdateResourceInput {
  name: String
  description: String
  status: ResourceStatus
  metadata: JSON
  tags: [String!]
}

input ResourceFilter {
  status: ResourceStatus
  createdAfter: DateTime
  createdBefore: DateTime
  tags: [String!]
  search: String
}

input ResourceOrderBy {
  field: ResourceOrderField!
  direction: OrderDirection!
}

enum ResourceOrderField {
  NAME
  CREATED_AT
  UPDATED_AT
  STATUS
}

enum OrderDirection {
  ASC
  DESC
}

Pagination

type ResourceConnection {
  edges: [ResourceEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type ResourceEdge {
  cursor: String!
  node: Resource!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

Payloads

type CreateResourcePayload {
  resource: Resource
  userErrors: [UserError!]!
}

type UpdateResourcePayload {
  resource: Resource
  userErrors: [UserError!]!
}

type DeleteResourcePayload {
  deletedResourceId: ID
  userErrors: [UserError!]!
}

type UserError {
  field: [String!]
  message: String!
  code: String!
}

Directives

directive @auth(requires: Role = USER) on FIELD_DEFINITION
directive @deprecated(reason: String) on FIELD_DEFINITION | ENUM_VALUE
directive @rateLimit(limit: Int!, window: Int!) on FIELD_DEFINITION
directive @cache(ttl: Int!) on FIELD_DEFINITION

enum Role {
  ADMIN
  USER
  GUEST
}

Custom Scalars

scalar DateTime
scalar JSON
scalar URL
scalar EmailAddress


## Common Elements for All API Types

### Security Considerations
- Authentication mechanism (JWT, OAuth2, API keys)
- Authorization rules (RBAC, ABAC)
- Rate limiting strategies
- Input validation rules
- CORS policies (for REST/GraphQL)
- TLS requirements

### Error Handling
- Consistent error codes and messages
- Proper HTTP status codes (REST)
- gRPC status codes (gRPC)
- GraphQL error extensions (GraphQL)

### Versioning Strategy
- URL versioning for REST (/v1/, /v2/)
- Package versioning for gRPC (v1, v2)
- Schema evolution for GraphQL

### Documentation Requirements
- Complete field descriptions
- Example requests and responses
- Authentication examples
- Error scenarios
- Rate limit information

## Update Metadata

After generating the API specification, update spec.json:
```json
{
  "phase": "api-defined",
  "api_type": "[rest|grpc|graphql]",
  "endpoints_count": [number],
  "approvals": {
    "schema": {
      "approved": true
    },
    "api": {
      "generated": true,
      "approved": false
    }
  },
  "updated_at": "current_timestamp"
}

Output

Write .kiro/specs/[FEATURE_NAME]/api.md with the complete API specification based on the selected type:

REST: OpenAPI 3.0 specification
gRPC: Protocol Buffers definition with service configuration
GraphQL: Complete GraphQL schema with types, queries, mutations, and subscriptions

Install spec-api and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

# API Specification Design ## Parse Arguments and Determine API Type Feature and API type from arguments: **{{arguments}}** **Expected formats:** - `feature-name` (defaults to REST) - `feature-name --type rest` - `feature-name --type grpc` - `feature-name --type graphql` **Instructions:** 1. Parse {{arguments}} to extract feature name and API type 2. If `--type` flag is present, use the specified type (rest/grpc/graphql) 3. If no `--type` flag, default to REST 4. Generate appropriate API specification based on the selected type ## Context Validation ### Previous Phases Check - Use cases: @.kiro/specs/{{arguments}}/usecase.md - Sequence diagrams: @.kiro/specs/{{arguments}}/sequence.md - Database schema: @.kiro/specs/{{arguments}}/schema.md - Spec metadata: @.kiro/specs/{{arguments}}/spec.json **CRITICAL**: API design requires approved schema and sequence diagrams. ## Interactive Approval Before generating API spec, ask the user: ``` Ready to generate [API_TYPE] API specification for [FEATURE_NAME]? Database schema should be reviewed first. Have you reviewed schema.md? [y/N]: ``` **Note:** Replace [API_TYPE] with the detected type and [FEATURE_NAME] with the extracted feature name. If 'N': Stop and request review of schema first. If 'y': Update spec.json to mark schema as approved and proceed: ```json { "approvals": { "schema": { "generated": true, "approved": true } } } ``` ## Task: Generate API Specification Based on the detected API type, generate the appropriate specification: ### For REST API (default or --type rest) Generate api.md with complete OpenAPI 3.0 specification: #### 1. REST API Document Structure ```markdown # API Specification: [Feature Name] ## Overview RESTful API design based on sequence diagrams and database schema. ## API Design Principles - RESTful: Follow REST conventions - Consistent: Uniform response format - Versioned: API versioning strategy - Documented: OpenAPI 3.0 specification - Secure: Authentication and authorization ## Base Configuration ### Base URL ``` Development: http://localhost:8080/api/v1 Staging: https://staging.example.com/api/v1 Environment variable: https://{env}.example.com/api/v1 ``` ### Authentication ```yaml securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ``` ### Common Headers ```yaml headers: X-Request-ID: description: Unique request identifier for tracing schema: type: string format: uuid X-Client-Version: description: Client application version schema: type: string ``` ## API Endpoints ### Analytics Overview ```yaml /analytics/overview: get: summary: Get analytics overview operationId: getAnalyticsOverview tags: - Analytics security: - bearerAuth: [] parameters: - name: start_date in: query required: false schema: type: string format: date-time example: "2025-01-01T00:00:00Z" description: Start date for analytics period (ISO 8601) - name: end_date in: query required: false schema: type: string format: date-time example: "2025-01-31T23:59:59Z" description: End date for analytics period (ISO 8601) responses: 200: description: Analytics overview retrieved successfully content: application/json: schema: $ref: '#/components/schemas/AnalyticsOverview' example: total_sent: 10000 total_delivered: 9500 open_rate: 25.5 click_rate: 3.2 bounce_rate: 5.0 period: start: "2025-01-01T00:00:00Z" end: "2025-01-31T23:59:59Z" 400: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: "INVALID_DATE_RANGE" message: "End date must be after start date" 401: $ref: '#/components/responses/UnauthorizedError' 500: $ref: '#/components/responses/InternalServerError' ``` ### Campaign Metrics ```yaml /analytics/campaigns: get: summary: Get campaign metrics list operationId: getCampaignMetrics tags: - Analytics security: - bearerAuth: [] parameters: - name: page in: query schema: type: integer minimum: 1 default: 1 - name: per_page in: query schema: type: integer minimum: 1 maximum: 100 default: 20 - name: sort_by in: query schema: type: string enum: [created_at, open_rate, click_rate, sent_count] default: created_at - name: sort_order in: query schema: type: string enum: [asc, desc] default: desc - name: start_date in: query schema: type: string format: date-time - name: end_date in: query schema: type: string format: date-time - name: status in: query schema: type: string enum: [draft, scheduled, sending, sent, failed] responses: 200: description: Campaign metrics retrieved successfully content: application/json: schema: type: object properties: campaigns: type: array items: $ref: '#/components/schemas/CampaignMetrics' pagination: $ref: '#/components/schemas/Pagination' example: campaigns: - id: "550e8400-e29b-41d4-a716-446655440000" name: "January Newsletter" status: "sent" sent_count: 5000 open_rate: 28.5 click_rate: 4.2 created_at: "2025-01-15T10:00:00Z" pagination: page: 1 per_page: 20 total: 45 total_pages: 3 ``` ### Campaign Details ```yaml /analytics/campaigns/{campaign_id}: get: summary: Get detailed campaign analytics operationId: getCampaignDetails tags: - Analytics security: - bearerAuth: [] parameters: - name: campaign_id in: path required: true schema: type: string format: uuid responses: 200: description: Campaign details retrieved successfully content: application/json: schema: $ref: '#/components/schemas/CampaignDetails' 404: description: Campaign not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ``` ### Time Series Data ```yaml /analytics/time-series: get: summary: Get time series analytics data operationId: getTimeSeries tags: - Analytics security: - bearerAuth: [] parameters: - name: campaign_id in: query schema: type: string format: uuid description: Optional campaign filter - name: metric_type in: query required: true schema: type: string enum: [opens, clicks, bounces, unsubscribes] - name: aggregation in: query schema: type: string enum: [hour, day, week, month] default: day - name: start_date in: query required: true schema: type: string format: date-time - name: end_date in: query required: true schema: type: string format: date-time responses: 200: description: Time series data retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TimeSeriesData' ``` ### Export Analytics ```yaml /analytics/export: post: summary: Export analytics data operationId: exportAnalytics tags: - Analytics security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - export_type - format properties: export_type: type: string enum: [overview, campaigns, subscribers, events] format: type: string enum: [csv, xlsx, json] campaign_ids: type: array items: type: string format: uuid start_date: type: string format: date-time end_date: type: string format: date-time email_delivery: type: boolean default: false description: Send export via email for large files responses: 200: description: Export completed immediately content: application/csv: schema: type: string format: binary 202: description: Export queued for processing content: application/json: schema: type: object properties: export_id: type: string format: uuid status: type: string enum: [queued, processing] message: type: string ``` ## Component Schemas ### AnalyticsOverview ```yaml AnalyticsOverview: type: object required: - total_sent - total_delivered - open_rate - click_rate properties: total_sent: type: integer minimum: 0 total_delivered: type: integer minimum: 0 unique_opens: type: integer minimum: 0 unique_clicks: type: integer minimum: 0 open_rate: type: number format: float minimum: 0 maximum: 100 click_rate: type: number format: float minimum: 0 maximum: 100 bounce_rate: type: number format: float minimum: 0 maximum: 100 unsubscribe_rate: type: number format: float minimum: 0 maximum: 100 period: type: object properties: start: type: string format: date-time end: type: string format: date-time ``` ### ErrorResponse ```yaml ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message details: type: array items: type: object properties: field: type: string message: type: string request_id: type: string format: uuid ``` ### Pagination ```yaml Pagination: type: object required: - page - per_page - total - total_pages properties: page: type: integer minimum: 1 per_page: type: integer minimum: 1 maximum: 100 total: type: integer minimum: 0 total_pages: type: integer minimum: 0 has_next: type: boolean has_prev: type: boolean ``` ## Response Examples ### Success Response Pattern ```json { "data": { // Response payload }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2025-01-15T10:00:00Z" } } ``` ### Error Response Pattern ```json { "error": { "code": "VALIDATION_ERROR", "message": "Invalid request parameters", "details": [ { "field": "start_date", "message": "Invalid date format" } ], "request_id": "550e8400-e29b-41d4-a716-446655440000" } } ``` ## Error Codes | Code | HTTP Status | Description | |------|------------|-------------| | UNAUTHORIZED | 401 | Missing or invalid authentication | | FORBIDDEN | 403 | Insufficient permissions | | NOT_FOUND | 404 | Resource not found | | VALIDATION_ERROR | 400 | Request validation failed | | RATE_LIMIT_EXCEEDED | 429 | Too many requests | | INTERNAL_ERROR | 500 | Internal server error | | SERVICE_UNAVAILABLE | 503 | Service temporarily unavailable | ## Rate Limiting ```yaml headers: X-RateLimit-Limit: description: Request limit per hour schema: type: integer X-RateLimit-Remaining: description: Remaining requests in current window schema: type: integer X-RateLimit-Reset: description: Time when limit resets (Unix timestamp) schema: type: integer ``` ## Versioning Strategy - URL versioning: `/api/v1/`, `/api/v2/` - Breaking changes require new version - Deprecation notice: 6 months minimum - Sunset period: 12 months after deprecation ``` ### 2. API Design Best Practices Ensure API follows: - **RESTful conventions**: Proper HTTP methods and status codes - **Consistent naming**: snake_case for JSON, kebab-case for URLs - **Pagination**: Limit/offset or cursor-based - **Filtering**: Query parameters for filtering - **Sorting**: Consistent sort parameter format - **Error handling**: Consistent error response format ### 3. Security Considerations Include: - **Authentication**: JWT/OAuth2 specification - **Authorization**: Role-based access control - **Rate limiting**: Prevent abuse - **Input validation**: Parameter constraints - **CORS policy**: Cross-origin configuration ### 4. Update Metadata Update spec.json: ```json { "phase": "api-defined", "endpoints_count": [number], "approvals": { "usecase": { "approved": true }, "sequence": { "approved": true }, "schema": { "approved": true }, "api": { "generated": true, "approved": false } }, "updated_at": "current_timestamp" } ``` ## Instructions 1. **Review sequence diagrams** - Understand all interactions 2. **Map to REST endpoints** - Convert sequences to APIs 3. **Define request/response** - Complete payload schemas 4. **Add all parameters** - Query, path, headers 5. **Document error cases** - All possible errors 6. **Include examples** - Real request/response examples 7. **Add rate limiting** - Protect against abuse 8. **Define security** - Authentication/authorization 9. **Ensure consistency** - Naming, format, structure 10. **Update metadata** - Record completion Generate a complete API specification that **prevents integration issues** by defining exact contracts upfront. ### For gRPC API (--type grpc) Generate api.md with Protocol Buffers specification: #### 1. gRPC API Document Structure ```markdown # gRPC API Specification: [Feature Name] ## Overview gRPC service design based on sequence diagrams and database schema. ## Service Definition ### Proto File: [feature_name].proto ```protobuf syntax = "proto3"; package [feature].v1; import "google/api/annotations.proto"; import "google/protobuf/timestamp.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/wrappers.proto"; service [FeatureName]Service { // Service methods based on sequence diagrams rpc GetResource(GetResourceRequest) returns (GetResourceResponse) { option (google.api.http) = { get: "/v1/resources/{id}" }; } // Streaming RPC for real-time updates rpc StreamUpdates(StreamRequest) returns (stream UpdateResponse); // Bidirectional streaming rpc Chat(stream ChatMessage) returns (stream ChatMessage); } ``` ## Message Definitions ```protobuf message GetResourceRequest { string id = 1; bool include_details = 2; } message GetResourceResponse { Resource resource = 1; google.protobuf.Timestamp retrieved_at = 2; } message Resource { string id = 1; string name = 2; Status status = 3; map<string, string> metadata = 4; repeated string tags = 5; } enum Status { STATUS_UNSPECIFIED = 0; STATUS_ACTIVE = 1; STATUS_INACTIVE = 2; STATUS_DELETED = 3; } ``` ## Error Handling ```protobuf message ErrorDetails { string code = 1; string message = 2; map<string, string> metadata = 3; } ``` ## Service Configuration ```yaml type: google.api.Service config_version: 3 name: [service].example.com apis: - name: [feature].v1.[FeatureName]Service authentication: rules: - selector: "*" requirements: - provider_id: bearer http: rules: - selector: [feature].v1.[FeatureName]Service.GetResource get: /v1/resources/{id} ``` ``` ### For GraphQL API (--type graphql) Generate api.md with GraphQL schema: #### 1. GraphQL API Document Structure ```markdown # GraphQL API Specification: [Feature Name] ## Overview GraphQL schema design based on sequence diagrams and database schema. ## Schema Definition ### Type System ```graphql schema { query: Query mutation: Mutation subscription: Subscription } type Query { # Single resource query resource(id: ID!): Resource # List resources with pagination resources( first: Int after: String last: Int before: String filter: ResourceFilter orderBy: ResourceOrderBy ): ResourceConnection! # Search resources searchResources( query: String! limit: Int = 10 ): [Resource!]! } type Mutation { # Create resource createResource(input: CreateResourceInput!): CreateResourcePayload! # Update resource updateResource(id: ID!, input: UpdateResourceInput!): UpdateResourcePayload! # Delete resource deleteResource(id: ID!): DeleteResourcePayload! } type Subscription { # Subscribe to resource changes resourceUpdated(id: ID!): Resource! # Subscribe to all changes allResourcesUpdated(filter: ResourceFilter): Resource! } ``` ## Object Types ```graphql type Resource { id: ID! name: String! description: String status: ResourceStatus! createdAt: DateTime! updatedAt: DateTime! createdBy: User! metadata: JSON tags: [String!]! } type User { id: ID! email: String! name: String! resources: [Resource!]! } enum ResourceStatus { DRAFT ACTIVE ARCHIVED DELETED } ``` ## Input Types ```graphql input CreateResourceInput { name: String! description: String status: ResourceStatus = DRAFT metadata: JSON tags: [String!] } input UpdateResourceInput { name: String description: String status: ResourceStatus metadata: JSON tags: [String!] } input ResourceFilter { status: ResourceStatus createdAfter: DateTime createdBefore: DateTime tags: [String!] search: String } input ResourceOrderBy { field: ResourceOrderField! direction: OrderDirection! } enum ResourceOrderField { NAME CREATED_AT UPDATED_AT STATUS } enum OrderDirection { ASC DESC } ``` ## Pagination ```graphql type ResourceConnection { edges: [ResourceEdge!]! pageInfo: PageInfo! totalCount: Int! } type ResourceEdge { cursor: String! node: Resource! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } ``` ## Payloads ```graphql type CreateResourcePayload { resource: Resource userErrors: [UserError!]! } type UpdateResourcePayload { resource: Resource userErrors: [UserError!]! } type DeleteResourcePayload { deletedResourceId: ID userErrors: [UserError!]! } type UserError { field: [Strin

{ "prompt": "# API Specification Design\n\n## Parse Arguments and Determine API Type\n\nFeature and API type from arguments: **{{arguments}}**\n\n**Expected formats:**\n- `feature-name` (defaults to REST)\n- `feature-name --type rest`\n- `feature-name --type grpc`\n- `feature-name --type graphql`\n\n**Instructions:**\n1. Parse {{arguments}} to extract feature name and API type\n2. If `--type` flag is present, use the specified type (rest/grpc/graphql)\n3. If no `--type` flag, default to REST\n4. Generate appropriate API specification based on the selected type\n\n## Context Validation\n\n### Previous Phases Check\n\n- Use cases: @.kiro/specs/{{arguments}}/usecase.md\n- Sequence diagrams: @.kiro/specs/{{arguments}}/sequence.md\n- Database schema: @.kiro/specs/{{arguments}}/schema.md\n- Spec metadata: @.kiro/specs/{{arguments}}/spec.json\n\n**CRITICAL**: API design requires approved schema and sequence diagrams.\n\n## Interactive Approval\n\nBefore generating API spec, ask the user:\n```\nReady to generate [API_TYPE] API specification for [FEATURE_NAME]?\nDatabase schema should be reviewed first.\nHave you reviewed schema.md? [y/N]: \n```\n\n**Note:** Replace [API_TYPE] with the detected type and [FEATURE_NAME] with the extracted feature name.\n\nIf 'N': Stop and request review of schema first.\nIf 'y': Update spec.json to mark schema as approved and proceed:\n```json\n{\n \"approvals\": {\n \"schema\": {\n \"generated\": true,\n \"approved\": true\n }\n }\n}\n```\n\n## Task: Generate API Specification\n\nBased on the detected API type, generate the appropriate specification:\n\n### For REST API (default or --type rest)\n\nGenerate api.md with complete OpenAPI 3.0 specification:\n\n#### 1. REST API Document Structure\n\n```markdown\n# API Specification: [Feature Name]\n\n## Overview\nRESTful API design based on sequence diagrams and database schema.\n\n## API Design Principles\n- RESTful: Follow REST conventions\n- Consistent: Uniform response format\n- Versioned: API versioning strategy\n- Documented: OpenAPI 3.0 specification\n- Secure: Authentication and authorization\n\n## Base Configuration\n\n### Base URL\n```\nDevelopment: http://localhost:8080/api/v1\nStaging: https://staging.example.com/api/v1\nEnvironment variable: https://{env}.example.com/api/v1\n```\n\n### Authentication\n```yaml\nsecuritySchemes:\n bearerAuth:\n type: http\n scheme: bearer\n bearerFormat: JWT\n```\n\n### Common Headers\n```yaml\nheaders:\n X-Request-ID:\n description: Unique request identifier for tracing\n schema:\n type: string\n format: uuid\n X-Client-Version:\n description: Client application version\n schema:\n type: string\n```\n\n## API Endpoints\n\n### Analytics Overview\n```yaml\n/analytics/overview:\n get:\n summary: Get analytics overview\n operationId: getAnalyticsOverview\n tags:\n - Analytics\n security:\n - bearerAuth: []\n parameters:\n - name: start_date\n in: query\n required: false\n schema:\n type: string\n format: date-time\n example: \"2025-01-01T00:00:00Z\"\n description: Start date for analytics period (ISO 8601)\n - name: end_date\n in: query\n required: false\n schema:\n type: string\n format: date-time\n example: \"2025-01-31T23:59:59Z\"\n description: End date for analytics period (ISO 8601)\n responses:\n 200:\n description: Analytics overview retrieved successfully\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/AnalyticsOverview'\n example:\n total_sent: 10000\n total_delivered: 9500\n open_rate: 25.5\n click_rate: 3.2\n bounce_rate: 5.0\n period:\n start: \"2025-01-01T00:00:00Z\"\n end: \"2025-01-31T23:59:59Z\"\n 400:\n description: Invalid request parameters\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/ErrorResponse'\n example:\n error:\n code: \"INVALID_DATE_RANGE\"\n message: \"End date must be after start date\"\n 401:\n $ref: '#/components/responses/UnauthorizedError'\n 500:\n $ref: '#/components/responses/InternalServerError'\n```\n\n### Campaign Metrics\n```yaml\n/analytics/campaigns:\n get:\n summary: Get campaign metrics list\n operationId: getCampaignMetrics\n tags:\n - Analytics\n security:\n - bearerAuth: []\n parameters:\n - name: page\n in: query\n schema:\n type: integer\n minimum: 1\n default: 1\n - name: per_page\n in: query\n schema:\n type: integer\n minimum: 1\n maximum: 100\n default: 20\n - name: sort_by\n in: query\n schema:\n type: string\n enum: [created_at, open_rate, click_rate, sent_count]\n default: created_at\n - name: sort_order\n in: query\n schema:\n type: string\n enum: [asc, desc]\n default: desc\n - name: start_date\n in: query\n schema:\n type: string\n format: date-time\n - name: end_date\n in: query\n schema:\n type: string\n format: date-time\n - name: status\n in: query\n schema:\n type: string\n enum: [draft, scheduled, sending, sent, failed]\n responses:\n 200:\n description: Campaign metrics retrieved successfully\n content:\n application/json:\n schema:\n type: object\n properties:\n campaigns:\n type: array\n items:\n $ref: '#/components/schemas/CampaignMetrics'\n pagination:\n $ref: '#/components/schemas/Pagination'\n example:\n campaigns:\n - id: \"550e8400-e29b-41d4-a716-446655440000\"\n name: \"January Newsletter\"\n status: \"sent\"\n sent_count: 5000\n open_rate: 28.5\n click_rate: 4.2\n created_at: \"2025-01-15T10:00:00Z\"\n pagination:\n page: 1\n per_page: 20\n total: 45\n total_pages: 3\n```\n\n### Campaign Details\n```yaml\n/analytics/campaigns/{campaign_id}:\n get:\n summary: Get detailed campaign analytics\n operationId: getCampaignDetails\n tags:\n - Analytics\n security:\n - bearerAuth: []\n parameters:\n - name: campaign_id\n in: path\n required: true\n schema:\n type: string\n format: uuid\n responses:\n 200:\n description: Campaign details retrieved successfully\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/CampaignDetails'\n 404:\n description: Campaign not found\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/ErrorResponse'\n```\n\n### Time Series Data\n```yaml\n/analytics/time-series:\n get:\n summary: Get time series analytics data\n operationId: getTimeSeries\n tags:\n - Analytics\n security:\n - bearerAuth: []\n parameters:\n - name: campaign_id\n in: query\n schema:\n type: string\n format: uuid\n description: Optional campaign filter\n - name: metric_type\n in: query\n required: true\n schema:\n type: string\n enum: [opens, clicks, bounces, unsubscribes]\n - name: aggregation\n in: query\n schema:\n type: string\n enum: [hour, day, week, month]\n default: day\n - name: start_date\n in: query\n required: true\n schema:\n type: string\n format: date-time\n - name: end_date\n in: query\n required: true\n schema:\n type: string\n format: date-time\n responses:\n 200:\n description: Time series data retrieved successfully\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/TimeSeriesData'\n```\n\n### Export Analytics\n```yaml\n/analytics/export:\n post:\n summary: Export analytics data\n operationId: exportAnalytics\n tags:\n - Analytics\n security:\n - bearerAuth: []\n requestBody:\n required: true\n content:\n application/json:\n schema:\n type: object\n required:\n - export_type\n - format\n properties:\n export_type:\n type: string\n enum: [overview, campaigns, subscribers, events]\n format:\n type: string\n enum: [csv, xlsx, json]\n campaign_ids:\n type: array\n items:\n type: string\n format: uuid\n start_date:\n type: string\n format: date-time\n end_date:\n type: string\n format: date-time\n email_delivery:\n type: boolean\n default: false\n description: Send export via email for large files\n responses:\n 200:\n description: Export completed immediately\n content:\n application/csv:\n schema:\n type: string\n format: binary\n 202:\n description: Export queued for processing\n content:\n application/json:\n schema:\n type: object\n properties:\n export_id:\n type: string\n format: uuid\n status:\n type: string\n enum: [queued, processing]\n message:\n type: string\n```\n\n## Component Schemas\n\n### AnalyticsOverview\n```yaml\nAnalyticsOverview:\n type: object\n required:\n - total_sent\n - total_delivered\n - open_rate\n - click_rate\n properties:\n total_sent:\n type: integer\n minimum: 0\n total_delivered:\n type: integer\n minimum: 0\n unique_opens:\n type: integer\n minimum: 0\n unique_clicks:\n type: integer\n minimum: 0\n open_rate:\n type: number\n format: float\n minimum: 0\n maximum: 100\n click_rate:\n type: number\n format: float\n minimum: 0\n maximum: 100\n bounce_rate:\n type: number\n format: float\n minimum: 0\n maximum: 100\n unsubscribe_rate:\n type: number\n format: float\n minimum: 0\n maximum: 100\n period:\n type: object\n properties:\n start:\n type: string\n format: date-time\n end:\n type: string\n format: date-time\n```\n\n### ErrorResponse\n```yaml\nErrorResponse:\n type: object\n required:\n - error\n properties:\n error:\n type: object\n required:\n - code\n - message\n properties:\n code:\n type: string\n description: Machine-readable error code\n message:\n type: string\n description: Human-readable error message\n details:\n type: array\n items:\n type: object\n properties:\n field:\n type: string\n message:\n type: string\n request_id:\n type: string\n format: uuid\n```\n\n### Pagination\n```yaml\nPagination:\n type: object\n required:\n - page\n - per_page\n - total\n - total_pages\n properties:\n page:\n type: integer\n minimum: 1\n per_page:\n type: integer\n minimum: 1\n maximum: 100\n total:\n type: integer\n minimum: 0\n total_pages:\n type: integer\n minimum: 0\n has_next:\n type: boolean\n has_prev:\n type: boolean\n```\n\n## Response Examples\n\n### Success Response Pattern\n```json\n{\n \"data\": {\n // Response payload\n },\n \"meta\": {\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"timestamp\": \"2025-01-15T10:00:00Z\"\n }\n}\n```\n\n### Error Response Pattern\n```json\n{\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Invalid request parameters\",\n \"details\": [\n {\n \"field\": \"start_date\",\n \"message\": \"Invalid date format\"\n }\n ],\n \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n}\n```\n\n## Error Codes\n\n| Code | HTTP Status | Description |\n|------|------------|-------------|\n| UNAUTHORIZED | 401 | Missing or invalid authentication |\n| FORBIDDEN | 403 | Insufficient permissions |\n| NOT_FOUND | 404 | Resource not found |\n| VALIDATION_ERROR | 400 | Request validation failed |\n| RATE_LIMIT_EXCEEDED | 429 | Too many requests |\n| INTERNAL_ERROR | 500 | Internal server error |\n| SERVICE_UNAVAILABLE | 503 | Service temporarily unavailable |\n\n## Rate Limiting\n\n```yaml\nheaders:\n X-RateLimit-Limit:\n description: Request limit per hour\n schema:\n type: integer\n X-RateLimit-Remaining:\n description: Remaining requests in current window\n schema:\n type: integer\n X-RateLimit-Reset:\n description: Time when limit resets (Unix timestamp)\n schema:\n type: integer\n```\n\n## Versioning Strategy\n\n- URL versioning: `/api/v1/`, `/api/v2/`\n- Breaking changes require new version\n- Deprecation notice: 6 months minimum\n- Sunset period: 12 months after deprecation\n```\n\n### 2. API Design Best Practices\n\nEnsure API follows:\n- **RESTful conventions**: Proper HTTP methods and status codes\n- **Consistent naming**: snake_case for JSON, kebab-case for URLs\n- **Pagination**: Limit/offset or cursor-based\n- **Filtering**: Query parameters for filtering\n- **Sorting**: Consistent sort parameter format\n- **Error handling**: Consistent error response format\n\n### 3. Security Considerations\n\nInclude:\n- **Authentication**: JWT/OAuth2 specification\n- **Authorization**: Role-based access control\n- **Rate limiting**: Prevent abuse\n- **Input validation**: Parameter constraints\n- **CORS policy**: Cross-origin configuration\n\n### 4. Update Metadata\n\nUpdate spec.json:\n```json\n{\n \"phase\": \"api-defined\",\n \"endpoints_count\": [number],\n \"approvals\": {\n \"usecase\": {\n \"approved\": true\n },\n \"sequence\": {\n \"approved\": true\n },\n \"schema\": {\n \"approved\": true\n },\n \"api\": {\n \"generated\": true,\n \"approved\": false\n }\n },\n \"updated_at\": \"current_timestamp\"\n}\n```\n\n## Instructions\n\n1. **Review sequence diagrams** - Understand all interactions\n2. **Map to REST endpoints** - Convert sequences to APIs\n3. **Define request/response** - Complete payload schemas\n4. **Add all parameters** - Query, path, headers\n5. **Document error cases** - All possible errors\n6. **Include examples** - Real request/response examples\n7. **Add rate limiting** - Protect against abuse\n8. **Define security** - Authentication/authorization\n9. **Ensure consistency** - Naming, format, structure\n10. **Update metadata** - Record completion\n\nGenerate a complete API specification that **prevents integration issues** by defining exact contracts upfront.\n\n### For gRPC API (--type grpc)\n\nGenerate api.md with Protocol Buffers specification:\n\n#### 1. gRPC API Document Structure\n\n```markdown\n# gRPC API Specification: [Feature Name]\n\n## Overview\ngRPC service design based on sequence diagrams and database schema.\n\n## Service Definition\n\n### Proto File: [feature_name].proto\n\n```protobuf\nsyntax = \"proto3\";\n\npackage [feature].v1;\n\nimport \"google/api/annotations.proto\";\nimport \"google/protobuf/timestamp.proto\";\nimport \"google/protobuf/empty.proto\";\nimport \"google/protobuf/wrappers.proto\";\n\nservice [FeatureName]Service {\n // Service methods based on sequence diagrams\n rpc GetResource(GetResourceRequest) returns (GetResourceResponse) {\n option (google.api.http) = {\n get: \"/v1/resources/{id}\"\n };\n }\n \n // Streaming RPC for real-time updates\n rpc StreamUpdates(StreamRequest) returns (stream UpdateResponse);\n \n // Bidirectional streaming\n rpc Chat(stream ChatMessage) returns (stream ChatMessage);\n}\n```\n\n## Message Definitions\n\n```protobuf\nmessage GetResourceRequest {\n string id = 1;\n bool include_details = 2;\n}\n\nmessage GetResourceResponse {\n Resource resource = 1;\n google.protobuf.Timestamp retrieved_at = 2;\n}\n\nmessage Resource {\n string id = 1;\n string name = 2;\n Status status = 3;\n map<string, string> metadata = 4;\n repeated string tags = 5;\n}\n\nenum Status {\n STATUS_UNSPECIFIED = 0;\n STATUS_ACTIVE = 1;\n STATUS_INACTIVE = 2;\n STATUS_DELETED = 3;\n}\n```\n\n## Error Handling\n\n```protobuf\nmessage ErrorDetails {\n string code = 1;\n string message = 2;\n map<string, string> metadata = 3;\n}\n```\n\n## Service Configuration\n\n```yaml\ntype: google.api.Service\nconfig_version: 3\nname: [service].example.com\n\napis:\n - name: [feature].v1.[FeatureName]Service\n\nauthentication:\n rules:\n - selector: \"*\"\n requirements:\n - provider_id: bearer\n\nhttp:\n rules:\n - selector: [feature].v1.[FeatureName]Service.GetResource\n get: /v1/resources/{id}\n```\n```\n\n### For GraphQL API (--type graphql)\n\nGenerate api.md with GraphQL schema:\n\n#### 1. GraphQL API Document Structure\n\n```markdown\n# GraphQL API Specification: [Feature Name]\n\n## Overview\nGraphQL schema design based on sequence diagrams and database schema.\n\n## Schema Definition\n\n### Type System\n\n```graphql\nschema {\n query: Query\n mutation: Mutation\n subscription: Subscription\n}\n\ntype Query {\n # Single resource query\n resource(id: ID!): Resource\n \n # List resources with pagination\n resources(\n first: Int\n after: String\n last: Int\n before: String\n filter: ResourceFilter\n orderBy: ResourceOrderBy\n ): ResourceConnection!\n \n # Search resources\n searchResources(\n query: String!\n limit: Int = 10\n ): [Resource!]!\n}\n\ntype Mutation {\n # Create resource\n createResource(input: CreateResourceInput!): CreateResourcePayload!\n \n # Update resource\n updateResource(id: ID!, input: UpdateResourceInput!): UpdateResourcePayload!\n \n # Delete resource\n deleteResource(id: ID!): DeleteResourcePayload!\n}\n\ntype Subscription {\n # Subscribe to resource changes\n resourceUpdated(id: ID!): Resource!\n \n # Subscribe to all changes\n allResourcesUpdated(filter: ResourceFilter): Resource!\n}\n```\n\n## Object Types\n\n```graphql\ntype Resource {\n id: ID!\n name: String!\n description: String\n status: ResourceStatus!\n createdAt: DateTime!\n updatedAt: DateTime!\n createdBy: User!\n metadata: JSON\n tags: [String!]!\n}\n\ntype User {\n id: ID!\n email: String!\n name: String!\n resources: [Resource!]!\n}\n\nenum ResourceStatus {\n DRAFT\n ACTIVE\n ARCHIVED\n DELETED\n}\n```\n\n## Input Types\n\n```graphql\ninput CreateResourceInput {\n name: String!\n description: String\n status: ResourceStatus = DRAFT\n metadata: JSON\n tags: [String!]\n}\n\ninput UpdateResourceInput {\n name: String\n description: String\n status: ResourceStatus\n metadata: JSON\n tags: [String!]\n}\n\ninput ResourceFilter {\n status: ResourceStatus\n createdAfter: DateTime\n createdBefore: DateTime\n tags: [String!]\n search: String\n}\n\ninput ResourceOrderBy {\n field: ResourceOrderField!\n direction: OrderDirection!\n}\n\nenum ResourceOrderField {\n NAME\n CREATED_AT\n UPDATED_AT\n STATUS\n}\n\nenum OrderDirection {\n ASC\n DESC\n}\n```\n\n## Pagination\n\n```graphql\ntype ResourceConnection {\n edges: [ResourceEdge!]!\n pageInfo: PageInfo!\n totalCount: Int!\n}\n\ntype ResourceEdge {\n cursor: String!\n node: Resource!\n}\n\ntype PageInfo {\n hasNextPage: Boolean!\n hasPreviousPage: Boolean!\n startCursor: String\n endCursor: String\n}\n```\n\n## Payloads\n\n```graphql\ntype CreateResourcePayload {\n resource: Resource\n userErrors: [UserError!]!\n}\n\ntype UpdateResourcePayload {\n resource: Resource\n userErrors: [UserError!]!\n}\n\ntype DeleteResourcePayload {\n deletedResourceId: ID\n userErrors: [UserError!]!\n}\n\ntype UserError {\n field: [Strin", "variables": [ "arguments" ], "notes": "Design API specifications (REST/gRPC/GraphQL) with appropriate format Tools: Bash, Read, Write, Edit, MultiEdit, Update.", "metadata": { "source": { "provider": "github-claude-commands", "repository": "https://github.com/engineers-hub-ltd-in-house-project/kiro-sdd", "path": ".claude/commands/kiro/spec-api.md", "ref": "44375a2428ae2b90c4395e052a4261e247c0356f", "url": "https://github.com/engineers-hub-ltd-in-house-project/kiro-sdd/blob/44375a2428ae2b90c4395e052a4261e247c0356f/.claude/commands/kiro/spec-api.md", "key": "engineers-hub-ltd-in-house-project/kiro-sdd/.claude/commands/kiro/spec-api.md" } } }

About

API Specification Design

Parse Arguments and Determine API Type

Context Validation

Previous Phases Check

Interactive Approval

Task: Generate API Specification

For REST API (default or --type rest)

1. REST API Document Structure

Common Headers

API Endpoints

Analytics Overview

Campaign Metrics

Campaign Details

Time Series Data

Export Analytics

Component Schemas

AnalyticsOverview

ErrorResponse

Pagination

Response Examples

Success Response Pattern

Error Response Pattern

Error Codes

Rate Limiting

Versioning Strategy

Instructions

For gRPC API (--type grpc)

1. gRPC API Document Structure

Message Definitions

Error Handling

Service Configuration

Object Types

Input Types

Pagination

Payloads

Directives

Custom Scalars

Output

Install spec-api and it becomes one more candidate the router can pick - when it fits.

Use it

Manifest

Reviews