API Designer

Purpose

Design robust, scalable APIs including REST, GraphQL, and gRPC with proper versioning, documentation, and evolution strategies.

Activation Keywords

• API design, API architecture
• REST design, GraphQL schema
• gRPC, Protocol Buffers
• API versioning, deprecation
• API gateway

Core Capabilities

1. REST API Design

• Resource modeling
• URL structure
• HTTP methods semantics
• Status codes
• HATEOAS

2. GraphQL

• Schema design
• Type system
• Query optimization
• Subscription design
• Federation

3. gRPC

• Service definition
• Message design
• Streaming patterns
• Error handling
• Interceptors

4. API Gateway

• Routing
• Rate limiting
• Authentication
• Request transformation
• Response aggregation

5. Documentation

• OpenAPI 3.0
• GraphQL SDL
• Protocol Buffers
• API changelog

Design Principles

1. Consistency
   - Naming conventions
   - Error formats
   - Response structures

2. Evolvability
   - Versioning strategy
   - Backward compatibility
   - Deprecation policy

3. Security
   - Authentication
   - Authorization
   - Input validation

4. Performance
   - Pagination
   - Filtering
   - Field selection
   - Caching headers

API Design Checklist

## Endpoint Design
- [ ] Resources properly named (nouns, plural)
- [ ] Correct HTTP methods used
- [ ] Consistent URL structure
- [ ] Query params for filtering/sorting

## Response Design
- [ ] Consistent response envelope
- [ ] Proper status codes
- [ ] Error format standardized
- [ ] Pagination metadata included

## Security
- [ ] Authentication documented
- [ ] Authorization rules clear
- [ ] Rate limits defined
- [ ] Input validation rules

## Documentation
- [ ] All endpoints documented
- [ ] Examples for each endpoint
- [ ] Error codes documented
- [ ] Versioning strategy documented

Protocol Selection Guide

Example Usage

User: "Design API for a booking system"

API Designer Response:
1. Resource identification
   - /bookings, /users, /properties, /availability

2. Endpoint design
   - POST /bookings (create)
   - GET /properties/{id}/availability
   - PATCH /bookings/{id}/cancel

3. GraphQL alternative schema
4. Authentication strategy (OAuth2)
5. Versioning strategy (URL-based /v1/)
6. OpenAPI specification