api-design

name	api-design
description	Design and build professional APIs with REST, GraphQL, and gRPC. Master authentication, documentation, testing, and operational concerns.
sasmp_version	2.0.0
bonded_agent	03-api-development
bond_type	PRIMARY_BOND
atomic_operations	["ENDPOINT_DESIGN","AUTHENTICATION_SETUP","DOCUMENTATION_GENERATION","RATE_LIMITING_CONFIG"]
parameter_validation	{"query":{"type":"string","required":true,"minLength":5,"maxLength":2000},"api_type":{"type":"string","enum":["rest","graphql","grpc","websocket"],"required":false},"auth_method":{"type":"string","enum":["jwt","oauth2","api_key","session"],"required":false}}
retry_logic	{"max_attempts":3,"backoff":"exponential","initial_delay_ms":1000}
logging_hooks	{"on_invoke":"skill.api-design.invoked","on_success":"skill.api-design.completed","on_error":"skill.api-design.failed"}
exit_codes	{"SUCCESS":0,"INVALID_INPUT":1,"SECURITY_ISSUE":2,"SCHEMA_ERROR":3}

API Design Skill

Bonded to: api-development-agent

---

Quick Start

# Invoke api-design skill
"Design a REST API for user management with authentication"
"Implement JWT authentication for my FastAPI app"
"Generate OpenAPI documentation for my endpoints"

---

Instructions

1. Analyze Requirements: Understand client needs and data flow
2. Choose Paradigm: Select REST, GraphQL, or gRPC
3. Design Endpoints: Create resource-oriented API structure
4. Implement Security: Add authentication and authorization
5. Document API: Generate OpenAPI specification

---

API Paradigm Selection

Paradigm	Best For	Performance	Complexity
REST	Public APIs, CRUD, simple	Good	Low
GraphQL	Complex data, mobile clients	Good	Medium
gRPC	Internal services, real-time	Excellent	Medium
WebSocket	Bi-directional real-time	Excellent	Medium

---

Decision Tree

Client type?
    │
    ├─→ Public/Third-party → REST
    │
    ├─→ Mobile with complex data → GraphQL
    │
    ├─→ Internal microservices
    │     ├─→ High performance needed → gRPC
    │     └─→ Standard HTTP preferred → REST
    │
    └─→ Real-time bi-directional → WebSocket

---

Examples

Example 1: REST API Design

# OpenAPI 3.1 Specification
openapi: 3.1.0
info:
  title: User Management API
  version: 1.0