---
name: api-design
trigger: /design api
description: Design REST, GraphQL, or event-driven APIs
---

# Skill: API Design

## Trigger
`/design api [API name or endpoint description]`

## Description
Design API endpoints with TypeScript interfaces, request/response schemas, and error handling.

## Inputs
- description: string, what the API should do (required)

## Process
1. Read existing API contracts and design documents
2. Design the API endpoints following REST conventions (or GraphQL if the project uses it)
3. Define TypeScript interfaces for request and response types
4. Define error response format and HTTP status codes
5. Document authentication and authorisation requirements per endpoint
6. Identify rate limiting and pagination needs
7. Produce an API contract document
8. Flag endpoints that introduce new attack surface for appsec review

## Output
API contract document with TypeScript interfaces, endpoint definitions, and security requirements.

## Autonomy
- Tier 1: drafting the API contract
- Tier 2: if the API changes an existing approved contract

## Error Handling
- If requirements are unclear: ask for specific input/output expectations