---
name: api-management
description: Manage API lifecycle including design, development, documentation, versioning, security, monitoring, developer portal management, rate limiting, and API governance. Use when designing APIs, managing API gateways, documenting API endpoints, implementing API security, managing API versions, or tracking API usage. Triggers on phrases like "API design", "REST API", "API gateway", "API documentation", "OpenAPI", "API security", "rate limiting", "API versioning", "developer portal", "API governance".
---

# API Management & Governance

Design, deploy, secure, and manage APIs across their lifecycle while ensuring developer experience and governance compliance.

## Workflow

### 1. API Design & Development

1. **API design principles and standards**:
   - RESTful API design best practices
   - Resource naming and URL structure conventions
   - HTTP method usage (GET, POST, PUT, PATCH, DELETE)
   - Response format standardization (JSON, HATEOAS)
   - Error handling and error code standardization

2. **API specification and documentation**:
   - OpenAPI/Swagger specification development
   - API contract definition and validation
   - Interactive API documentation (Swagger UI, Redoc)
   - API changelog and deprecation notice
   - Example request/response documentation

3. **API versioning strategy**:
   - Versioning approach (URL path, header, media type)
   - Version lifecycle management
   - Backward compatibility guidelines
   - Deprecation timeline and communication
   - Multi-version support and sunset management

### 2. API Gateway & Runtime Management

1. **Gateway configuration and deployment**:
   - API gateway selection and setup (Kong, Apigee, AWS API Gateway)
   - Route configuration and path mapping
   - Protocol translation (HTTP, gRPC, WebSocket, GraphQL)
   - Load balancing and failover configuration
   - SSL/TLS termination and certificate management

2. **Rate limiting and throttling**:
   - Rate limit policy definition by API, consumer, tier
   - Quota management and enforcement
   - Burst handling and spike absorption
   - Rate limit header and remaining quota communication
   - Rate limit exception and whitelist management

3. **Request/response transformation**:
   - Request/response filtering and masking
   - Protocol and format transformation
   - Payload size validation and limiting
   - Header injection and manipulation
   - Content caching and response optimization

### 3. API Security

1. **Authentication and authorization**:
   - API key management and distribution
   - OAuth 2.0 / OpenID Connect implementation
   - JWT token validation and claim verification
   - Client certificate authentication
   - API consumer role-based access control

2. **Security enforcement**:
   - Input validation and sanitization
   - SQL injection and XSS prevention
   - DDoS protection and bot mitigation
   - IP whitelisting and geolocation filtering
   - Data encryption in transit and at rest

3. **Security monitoring and compliance**:
   - API threat detection and alerting
   - Security scan and vulnerability assessment
   - Penetration testing coordination
   - Compliance audit logging
   - OWASP API Security Top 10 compliance

### 4. API Monitoring & Analytics

1. **Performance monitoring**:
   - API response time tracking and SLA monitoring
   - Throughput and capacity monitoring
   - Error rate and error code tracking
   - Endpoint-level performance analysis
   - Performance degradation alert and escalation

2. **Usage analytics**:
   - API call volume and trend analysis
   - Consumer usage breakdown and trending
   - Geographic and source IP analysis
   - Popular endpoint identification
   - Usage anomaly detection

3. **Developer experience monitoring**:
   - API documentation engagement metrics
   - SDK and client library adoption
   - Developer support ticket analysis
   - API onboarding time tracking
   - Developer satisfaction survey

### 5. API Governance & Lifecycle

1. **API catalog and inventory**:
   - API registry and inventory management
   - API ownership and stewardship assignment
   - API classification (internal, partner, public)
   - API dependency mapping
   - API retirement and sunset planning

2. **Design review and approval**:
   - API design review board process
   - Design guideline compliance check
   - Security review and approval
   - Performance and scalability review
   - Documentation completeness verification

3. **Developer portal and enablement**:
   - Self-service developer portal setup
   - API discovery and documentation
   - SDK and code sample library
   - Sandbox environment and test data
   - Developer community and support

## Templates & Frameworks

### API Design Guidelines

```
API DESIGN GUIDELINES
======================

URL STRUCTURE:
  Format: /api/{version}/{resource}/{id}/{sub-resource}
  Example: /api/v2/accounts/12345/transactions
  Rules: Use nouns (not verbs), lowercase, hyphenated, plural resources

HTTP METHODS:
  GET: Retrieve resource (idempotent, no side effects)
  POST: Create new resource
  PUT: Full resource update (idempotent)
  PATCH: Partial resource update
  DELETE: Remove resource (idempotent)

RESPONSE FORMAT:
  Success (2xx): { "data": {...}, "meta": {...} }
  Error (4xx/5xx): { "error": { "code": "...", "message": "...", "details": [...] } }
  Pagination: { "data": [...], "meta": { "page": 1, "perPage": 20, "total": 150 } }

STATUS CODES:
  200: Success (GET, PUT, PATCH)
  201: Created (POST)
  204: No Content (DELETE)
  400: Bad Request (validation error)
  401: Unauthorized (missing/invalid auth)
  403: Forbidden (insufficient permissions)
  404: Not Found (resource doesn't exist)
  409: Conflict (duplicate or state conflict)
  422: Unprocessable Entity (semantic error)
  429: Too Many Requests (rate limit exceeded)
  500: Internal Server Error

RATE LIMITING:
  Standard tier: 1,000 requests/minute, 50,000/hour
  Premium tier: 5,000 requests/minute, 200,000/hour
  Enterprise tier: Custom limits per contract
  Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

VERSIONING:
  Strategy: URL path versioning (/api/v1/, /api/v2/)
  Major version: Breaking changes only
  Minor changes: Backward compatible, no version bump
  Deprecation: 12-month notice, sunset communication
  Support: Current + 1 previous version

DOCUMENTATION REQUIREMENTS:
  OpenAPI 3.0 specification (required for all APIs)
  Interactive documentation (Swagger UI or equivalent)
  Example requests and responses
  Authentication guide
  Error code reference
  Rate limit documentation
  SDK availability (preferred languages)
```

### API Health Dashboard

```
API HEALTH DASHBOARD — April 2025
===================================

API INVENTORY:
  Total APIs: 147
  Active: 128
  In development: 12
  Deprecated: 5
  Retired (sunset pending): 2

PERFORMANCE (LAST 7 DAYS):
  Avg response time: 142ms (SLA: <200ms ✓)
  p95 response time: 312ms (SLA: <500ms ✓)
  p99 response time: 587ms (SLA: <1000ms ✓)
  Total API calls: 24.7M
  Success rate: 99.2% ✓
  Error rate: 0.8% (within threshold ✓)

TOP APIs BY VOLUME:
  1. /api/v2/accounts: 8.2M calls (33.2%), avg 98ms
  2. /api/v2/transactions: 5.1M calls (20.7%), avg 156ms
  3. /api/v2/products: 4.3M calls (17.4%), avg 124ms
  4. /api/v2/users: 3.8M calls (15.4%), avg 89ms
  5. /api/v2/analytics: 1.9M calls (7.7%), avg 245ms ⚠

ERROR ANALYSIS:
  4xx errors: 0.5% (client errors — rate limit, validation, auth)
  5xx errors: 0.3% (server errors — timeout, internal error)
  Top error: 429 Too Many Requests (rate limit hit by 3 consumers)
  Top 5xx: Timeout on /api/v2/analytics (high-compute endpoint)

RATE LIMITING:
  Rate limit violations: 1,240 (0.005% of total calls)
  Consumers exceeding limit: 8 (3 external partners)
  Throttled requests: 3,420
  Rate limit policy adjustment needed: 2 consumers

SECURITY:
  Authentication failures: 892 (invalid/expired tokens)
  Authorization failures: 156 (insufficient permissions)
  Security alerts: 3 (unusual pattern detection — under review)
  Certificate expiry: 2 certs expiring within 30 days (renewal pending)

CONSUMER BREAKDOWN:
  Internal consumers: 78 (68% of traffic)
  Partner consumers: 24 (22% of traffic)
  Public consumers: 46 (10% of traffic)
  New consumers (this month): 7

SLA COMPLIANCE:
  Availability: 99.95% (SLA: 99.9% ✓)
  Response time: 97.8% within SLA (SLA: 95% ✓)
  Error rate: Within threshold ✓
  SLA breach this month: 0 ✓
```

## Integration Points

- API gateways (Kong, Apigee, AWS API Gateway, Azure API Management): Traffic management
- API design tools (Stoplight, Swagger Hub, Postman): Design and documentation
- Service mesh (Istio, Linkerd): Microservice API management
- Monitoring platforms (Datadog, New Relic, Dynatrace): Performance monitoring
- Developer portal platforms (Stoplight Portal, SwaggerHub): Self-service documentation
- CI/CD platforms: API deployment automation
- Security tools (OWASP ZAP, Burp Suite): API security testing
- Authentication services (Auth0, Okta, Keycloak): API authentication

## Edge Cases

- **High-traffic API scaling**: Auto-scaling configuration; response caching; CDN integration; read replica routing; connection pooling optimization
- **API backward compatibility challenges**: API versioning discipline; contract testing; consumer notification process; compatibility testing pipeline
- **Third-party API dependency management**: Circuit breaker pattern; fallback response strategy; rate limit negotiation; SLA monitoring; redundancy planning
- **GraphQL vs REST API decision**: Query flexibility vs caching; schema design complexity; developer ecosystem; organizational API expertise
- **API monetization**: Tiered pricing model; usage tracking and billing; free tier management; enterprise custom pricing; usage alert and cap

## Output

### API Governance Report

```
API GOVERNANCE REPORT — Q2 2025
=================================

COMPLIANCE STATUS:
  APIs with current OpenAPI spec: 122/128 (95.3%) ✓
  APIs with documentation: 126/128 (98.4%) ✓
  APIs passing security scan: 127/128 (99.2%) ✓
  APIs meeting SLA: 124/128 (96.9%) ✓
  APIs with defined owner: 128/128 (100%) ✓

API LIFECYCLE DISTRIBUTION:
  Design phase: 8
  Development: 14
  Testing/QA: 6
  Production (current): 98
  Production (previous version): 20
  Deprecated (sunset notice): 5
  Scheduled retirement: 2

DESIGN REVIEW METRICS:
  APIs reviewed this quarter: 18
  Average review time: 4.2 days
  Design guideline compliance: 89%
  Security review compliance: 100%
  Documentation completeness at launch: 94%

DEVELOPER EXPERIENCE:
  Developer portal visits: 23,400
  SDK downloads: 4,560
  API key registrations: 189
  Average onboarding time: 2.3 days
  Developer satisfaction: 4.1/5.0
  Support tickets (API-related): 67

INNOVATION AND IMPROVEMENT:
  API modernization in progress: 5 (gRPC migration, GraphQL addition)
  New SDK languages planned: Python, Go
  Developer community growth: +12% QoQ
  API marketplace launch: Q3 2025
```

## Trigger Phrases

"API design", "REST API", "API gateway", "API documentation", "OpenAPI", "API security", "rate limiting", "API versioning", "developer portal", "API governance", "API lifecycle", "GraphQL", "API key", "API monitoring", "API catalog"