Api Designer Examples
Externalized from the agent definition per the few-shot-examples rule (#1587).
API Designer — Worked Examples
Externalized from the agent definition per the few-shot-examples rule (#1587).
Few-Shot Examples
Example 1: Simple - REST Endpoint Specification
Input: "Design a REST API endpoint for retrieving a single user by ID. Include OpenAPI specification with response schema, error codes, and security requirements."
Output:
openapi: 3.1.0
info:
title: User Management API
version: 1.0.0
description: API for managing user accounts
paths:
/api/users/{userId}:
get:
summary: Get user by ID
description: Retrieves a single user account by unique identifier
operationId: getUserById
tags:
- users
security:
- bearerAuth: []
parameters:
- name: userId
in: path
required: true
description: Unique identifier for the user
schema:
type: string
format: uuid
example: "550e8400-e29b-41d4-a716-446655440000"
responses:
'200':
description: User retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
success:
value:
id: "550e8400-e29b-41d4-a716-446655440000"
email: "[email protected]"
firstName: "John"
lastName: "Doe"
role: "user"
isActive: true
createdAt: "2024-01-15T10:30:00Z"
updatedAt: "2024-01-20T14:45:00Z"
'401':
description: Authentication required
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
unauthorized:
value:
type: "https://api.example.com/errors/unauthorized"
title: "Unauthorized"
status: 401
detail: "Valid authentication token required"
instance: "/api/users/550e8400-e29b-41d4-a716-446655440000"
'403':
description: Insufficient permissions
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
forbidden:
value:
type: "https://api.example.com/errors/forbidden"
title: "Forbidden"
status: 403
detail: "Insufficient permissions to access this resource"
instance: "/api/users/550e8400-e29b-41d4-a716-446655440000"
'404':
description: User not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
notFound:
value:
type: "https://api.example.com/errors/not-found"
title: "Not Found"
status: 404
detail: "User with ID '550e8400-e29b-41d4-a716-446655440000' not found"
instance: "/api/users/550e8400-e29b-41d4-a716-446655440000"
'500':
description: Internal server error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
components:
schemas:
User:
type: object
required:
- id
- email
- firstName
- lastName
- role
- isActive
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: Unique identifier for the user
email:
type: string
format: email
description: User's email address
firstName:
type: string
minLength: 1
maxLength: 100
description: User's first name
lastName:
type: string
minLength: 1
maxLength: 100
description: User's last name
role:
type: string
enum: [admin, user, guest]
description: User's role in the system
isActive:
type: boolean
description: Whether the user account is active
createdAt:
type: string
format: date-time
description: Timestamp when user was created
updatedAt:
type: string
format: date-time
description: Timestamp when user was last updated
ProblemDetails:
type: object
required:
- type
- title
- status
properties:
type:
type: string
format: uri
description: URI reference identifying the problem type
title:
type: string
description: Short, human-readable summary of the problem
status:
type: integer
format: int32
description: HTTP status code
detail:
type: string
description: Human-readable explanation specific to this occurrence
instance:
type: string
format: uri
description: URI reference identifying the specific occurrence
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token obtained from /api/auth/loginWhy This Is Good:
- Complete OpenAPI specification: Uses OpenAPI 3.1.0 standard with all required fields and proper structure
- Rich error handling: Defines 401, 403, 404, 500 responses with RFC 7807 Problem Details format for consistency
- Detailed schema definitions: User schema includes validation constraints (min/max length, enum values, format specifications)
- Security-first: Explicit bearer authentication requirement with JWT format specification
- Concrete examples: Includes example values for both success and error responses to guide implementation
- Clear documentation: Every field has a description, making the API self-documenting
Example 2: Moderate - Payment API Error Handling
Input: "Design comprehensive error handling for a payment processing API. Cover validation errors (400), authentication failures (401), authorization issues (403), and internal errors (500). Use RFC 7807 Problem Details format with extension fields for payment-specific context."
Output:
openapi: 3.1.0
info:
title: Payment Processing API
version: 1.0.0
description: Secure payment processing with comprehensive error handling
paths:
/api/payments:
post:
summary: Process payment
description: Processes a payment transaction
operationId: processPayment
tags:
- payments
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequest'
responses:
'201':
description: Payment processed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
'400':
description: Validation error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/PaymentValidationProblem'
examples:
invalidAmount:
value:
type: "https://api.example.com/payments/errors/validation"
title: "Validation Error"
status: 400
detail: "Payment validation failed"
instance: "/api/payments"
errors:
- field: "amount"
code: "AMOUNT_TOO_SMALL"
message: "Amount must be at least 0.01"
rejectedValue: 0
- field: "currency"
code: "UNSUPPORTED_CURRENCY"
message: "Currency 'XYZ' is not supported"
rejectedValue: "XYZ"
supportedValues: ["USD", "EUR", "GBP"]
invalidCard:
value:
type: "https://api.example.com/payments/errors/validation"
title: "Validation Error"
status: 400
detail: "Payment method validation failed"
instance: "/api/payments"
errors:
- field: "paymentMethod.cardNumber"
code: "INVALID_CARD_NUMBER"
message: "Card number fails Luhn check"
rejectedValue: "****1234"
- field: "paymentMethod.expiryDate"
code: "CARD_EXPIRED"
message: "Card expired on 2023-12"
rejectedValue: "2023-12"
'401':
description: Authentication required
content:
application/problem+json:
schema:
$ref: '#/components/schemas/PaymentAuthenticationProblem'
examples:
missingToken:
value:
type: "https://api.example.com/payments/errors/authentication"
title: "Authentication Required"
status: 401
detail: "Valid bearer token required for payment processing"
instance: "/api/payments"
authenticationScheme: "Bearer"
realm: "payment-api"
expiredToken:
value:
type: "https://api.example.com/payments/errors/authentication"
title: "Token Expired"
status: 401
detail: "Authentication token expired at 2024-01-20T15:30:00Z"
instance: "/api/payments"
expiredAt: "2024-01-20T15:30:00Z"
authenticationScheme: "Bearer"
'403':
description: Insufficient permissions or payment declined
content:
application/problem+json:
schema:
$ref: '#/components/schemas/PaymentAuthorizationProblem'
examples:
insufficientPermissions:
value:
type: "https://api.example.com/payments/errors/forbidden"
title: "Insufficient Permissions"
status: 403
detail: "User lacks permission to process payments"
instance: "/api/payments"
requiredPermission: "payments:create"
userPermissions: ["payments:read"]
paymentDeclined:
value:
type: "https://api.example.com/payments/errors/declined"
title: "Payment Declined"
status: 403
detail: "Payment declined by payment processor"
instance: "/api/payments"
declineReason: "INSUFFICIENT_FUNDS"
declineCode: "51"
canRetry: false
merchantMessage: "Insufficient funds - request alternate payment method"
fraudSuspected:
value:
type: "https://api.example.com/payments/errors/declined"
title: "Payment Declined"
status: 403
detail: "Payment declined due to fraud detection"
instance: "/api/payments"
declineReason: "FRAUD_SUSPECTED"
declineCode: "59"
canRetry: false
merchantMessage: "Suspected fraud - contact issuer"
riskScore: 0.92
'429':
description: Rate limit exceeded
content:
application/problem+json:
schema:
$ref: '#/components/schemas/PaymentRateLimitProblem'
examples:
rateLimited:
value:
type: "https://api.example.com/payments/errors/rate-limit"
title: "Rate Limit Exceeded"
status: 429
detail: "Payment processing rate limit exceeded"
instance: "/api/payments"
rateLimit:
limit: 100
remaining: 0
resetAt: "2024-01-20T16:00:00Z"
'500':
description: Internal server error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/PaymentInternalErrorProblem'
examples:
processorTimeout:
value:
type: "https://api.example.com/payments/errors/internal"
title: "Payment Processor Timeout"
status: 500
detail: "Payment processor did not respond within timeout period"
instance: "/api/payments"
errorId: "err_1234567890abcdef"
canRetry: true
retryAfter: 30
supportContact: "[email protected]"
databaseError:
value:
type: "https://api.example.com/payments/errors/internal"
title: "Internal Server Error"
status: 500
detail: "An unexpected error occurred while processing payment"
instance: "/api/payments"
errorId: "err_fedcba0987654321"
canRetry: true
retryAfter: 60
supportContact: "[email protected]"
components:
schemas:
PaymentRequest:
type: object
required:
- amount
- currency
- paymentMethod
properties:
amount:
type: number
format: decimal
minimum: 0.01
description: Payment amount
currency:
type: string
enum: [USD, EUR, GBP]
description: Three-letter currency code
paymentMethod:
$ref: '#/components/schemas/PaymentMethod'
PaymentMethod:
type: object
required:
- type
- cardNumber
- expiryDate
- cvv
properties:
type:
type: string
enum: [card]
cardNumber:
type: string
pattern: '^[0-9]{13,19}$'
expiryDate:
type: string
pattern: '^[0-9]{4}-[0-9]{2}$'
description: Format YYYY-MM
cvv:
type: string
pattern: '^[0-9]{3,4}$'
PaymentResponse:
type: object
required:
- id
- status
- amount
- currency
properties:
id:
type: string
format: uuid
status:
type: string
enum: [succeeded, processing]
amount:
type: number
currency:
type: string
PaymentValidationProblem:
allOf:
- $ref: '#/components/schemas/BaseProblemDetails'
- type: object
required:
- errors
properties:
errors:
type: array
description: Detailed validation errors
items:
type: object
required:
- field
- code
- message
properties:
field:
type: string
description: JSON path to the invalid field
code:
type: string
description: Machine-readable error code
message:
type: string
description: Human-readable error message
rejectedValue:
description: The value that was rejected
supportedValues:
type: array
description: List of supported values (if applicable)
PaymentAuthenticationProblem:
allOf:
- $ref: '#/components/schemas/BaseProblemDetails'
- type: object
properties:
authenticationScheme:
type: string
description: Expected authentication scheme
realm:
type: string
description: Authentication realm
expiredAt:
type: string
format: date-time
description: When the token expired (if applicable)
PaymentAuthorizationProblem:
allOf:
- $ref: '#/components/schemas/BaseProblemDetails'
- type: object
properties:
requiredPermission:
type: string
description: Permission required for this operation
userPermissions:
type: array
items:
type: string
description: Permissions the user currently has
declineReason:
type: string
description: Reason payment was declined
declineCode:
type: string
description: Processor-specific decline code
canRetry:
type: boolean
description: Whether retrying might succeed
merchantMessage:
type: string
description: Message to display to merchant
riskScore:
type: number
format: float
minimum: 0
maximum: 1
description: Fraud risk score (if applicable)
PaymentRateLimitProblem:
allOf:
- $ref: '#/components/schemas/BaseProblemDetails'
- type: object
required:
- rateLimit
properties:
rateLimit:
type: object
required:
- limit
- remaining
- resetAt
properties:
limit:
type: integer
description: Maximum requests allowed
remaining:
type: integer
description: Requests remaining in window
resetAt:
type: string
format: date-time
description: When the rate limit resets
PaymentInternalErrorProblem:
allOf:
- $ref: '#/components/schemas/BaseProblemDetails'
- type: object
required:
- errorId
properties:
errorId:
type: string
description: Unique error identifier for support tracking
canRetry:
type: boolean
description: Whether retrying the request might succeed
retryAfter:
type: integer
description: Suggested retry delay in seconds
supportContact:
type: string
description: Contact information for support
BaseProblemDetails:
type: object
required:
- type
- title
- status
properties:
type:
type: string
format: uri
title:
type: string
status:
type: integer
detail:
type: string
instance:
type: string
format: uri
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWTWhy This Is Good:
- RFC 7807 compliance: Uses standard Problem Details format for all errors, ensuring consistency
- Payment-specific extensions: Adds domain-specific fields like `declineReason`, `declineCode`, `canRetry`, `riskScore` for actionable error handling
- Comprehensive error scenarios: Covers validation, authentication, authorization, rate limiting, and internal errors with realistic examples
- Merchant-friendly messages: Includes `merchantMessage` field with user-facing guidance on how to resolve issues
- Retry guidance: Explicit `canRetry` and `retryAfter` fields help clients implement smart retry logic
- Detailed validation errors: Array of field-level errors with machine-readable codes and human-readable messages
- Support tracking: Error IDs and support contact information enable effective troubleshooting
Example 3: Complex - API Versioning Strategy
Input: "Design an API versioning strategy for migrating from v1 to v2 of a user management API. The v2 API changes the user model structure and adds new required fields. Include deprecation headers, sunset policy, backward compatibility approach, and migration guide."
Output:
# API Versioning Strategy: User Management API v1 → v2
## Executive Summary
This document defines the versioning strategy for migrating the User Management API from v1 to v2. Version 2 introduces breaking changes to the user model structure and adds new required fields for enhanced security and compliance.
## Version Comparison
### v1 User Model (Current){ "id": "550e8400-e29b-41d4-a716-446655440000", "email": "[email protected]", "name": "John Doe", "role": "user", "createdAt": "2024-01-15T10:30:00Z" }
### v2 User Model (Target){ "id": "550e8400-e29b-41d4-a716-446655440000", "email": "[email protected]", "profile": { "firstName": "John", "lastName": "Doe", "displayName": "John Doe" }, "role": "user", "security": { "mfaEnabled": true, "lastPasswordChange": "2024-01-20T14:00:00Z" }, "metadata": { "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-20T14:00:00Z", "version": 2 } }
### Breaking Changes
| Change | Impact | Migration Required |
|--------|--------|-------------------|
| `name` → `profile.firstName` + `profile.lastName` | HIGH | Clients must split name field |
| New required field: `security.mfaEnabled` | HIGH | Clients must handle new field |
| New required field: `security.lastPasswordChange` | MEDIUM | Clients must handle new field |
| `createdAt` → `metadata.createdAt` | MEDIUM | Clients must update field path |
| Added `metadata.version` | LOW | Informational only |
## Versioning Approach
### URL-Based Versioning
v1: https://api.example.com/v1/users/{userId} v2: https://api.example.com/v2/users/{userId}
**Rationale**: URL-based versioning provides clear separation, simplifies routing, and allows independent evolution of each version.
### Deprecation Timeline
| Date | Milestone | Action |
|------|-----------|--------|
| 2024-02-01 | v2 Release | v2 API goes live, v1 continues working |
| 2024-02-01 | Deprecation Notice | v1 endpoints return `Deprecation` and `Sunset` headers |
| 2024-05-01 | Warning Phase | v1 endpoints return `410 Gone` for new clients |
| 2024-08-01 | Sunset | v1 endpoints removed from production |
**Deprecation Period**: 6 months from v2 release to v1 sunset
### Deprecation Headers (v1 Endpoints)
All v1 endpoints will return the following headers:
HTTP/1.1 200 OK Deprecation: true Sunset: Wed, 01 Aug 2024 00:00:00 GMT Link: https://api.example.com/docs/v1-to-v2-migration; rel="deprecation" X-API-Version: v1 X-API-Latest-Version: v2 X-API-Deprecation-Reason: "Version 1 is deprecated. Please migrate to v2."
### Backward Compatibility Strategy
#### Option 1: Dual-Mode Server (Recommended)
Both v1 and v2 endpoints exist simultaneously during the deprecation period.
**v1 Endpoint** (`/v1/users/{userId}`):
- Returns legacy format
- Internally transforms v2 data to v1 format
- Includes deprecation headers
**v2 Endpoint** (`/v2/users/{userId}`):
- Returns new format
- Native v2 data structure
**Implementation**:Internal data transformation layer
v1_response: name: "{{ user.profile.firstName }} {{ user.profile.lastName }}" email: "{{ user.email }}" role: "{{ user.role }}" createdAt: "{{ user.metadata.createdAt }}"
v2_response: profile: firstName: "{{ user.profile.firstName }}" lastName: "{{ user.profile.lastName }}" displayName: "{{ user.profile.firstName }} {{ user.profile.lastName }}" email: "{{ user.email }}" role: "{{ user.role }}" security: mfaEnabled: "{{ user.security.mfaEnabled }}" lastPasswordChange: "{{ user.security.lastPasswordChange }}" metadata: createdAt: "{{ user.metadata.createdAt }}" updatedAt: "{{ user.metadata.updatedAt }}" version: 2
#### Option 2: Accept-Version Header
Single URL with version negotiation via header:
GET /api/users/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1 Accept: application/json Accept-Version: v2
**Not Recommended**: Adds complexity, harder to route, caching issues.
## Migration Guide
### For API Consumers
#### Step 1: Test v2 in Development (Week 1-2)
Update base URL
OLD: https://api.example.com/v1/users NEW: https://api.example.com/v2/users
Test v2 endpoint
curl -H "Authorization: Bearer TOKEN" \ https://api.example.com/v2/users/550e8400-e29b-41d4-a716-446655440000
#### Step 2: Update Code to Handle v2 Response (Week 3-4)
**Before (v1)**:const user = await fetch('/v1/users/123'); console.log(user.name); // "John Doe"
**After (v2)**:const user = await fetch('/v2/users/123'); console.log(user.profile.firstName); // "John" console.log(user.profile.lastName); // "Doe" console.log(user.profile.displayName); // "John Doe"
#### Step 3: Update POST/PUT Requests (Week 5)
**Before (v1)**:POST /v1/users { "email": "[email protected]", "name": "New User", "role": "user" }
**After (v2)**:POST /v2/users { "email": "[email protected]", "profile": { "firstName": "New", "lastName": "User" }, "role": "user", "security": { "mfaEnabled": false } }
#### Step 4: Deploy to Production (Week 6)
- Gradual rollout with feature flags
- Monitor error rates
- Rollback plan ready
### Code Migration Examples
#### JavaScript/TypeScript
// Helper function for backward compatibility function normalizeUser(user: any, apiVersion: 'v1' | 'v2') { if (apiVersion === 'v1') { return { id: user.id, email: user.email, firstName: user.name.split(' ')[0], lastName: user.name.split(' ').slice(1).join(' '), role: user.role, mfaEnabled: false, // v1 doesn't have this createdAt: user.createdAt, }; } else { return { id: user.id, email: user.email, firstName: user.profile.firstName, lastName: user.profile.lastName, role: user.role, mfaEnabled: user.security.mfaEnabled, createdAt: user.metadata.createdAt, }; } }
// Usage const user = await getUserById('123', 'v2'); const normalized = normalizeUser(user, 'v2');
#### Python
def normalize_user(user: dict, api_version: str) -> dict: """Normalize user data across API versions.""" if api_version == 'v1': name_parts = user['name'].split(' ', 1) return { 'id': user['id'], 'email': user['email'], 'first_name': name_parts[0], 'last_name': name_parts[1] if len(name_parts) > 1 else '', 'role': user['role'], 'mfa_enabled': False, 'created_at': user['createdAt'], } else: # v2 return { 'id': user['id'], 'email': user['email'], 'first_name': user['profile']['firstName'], 'last_name': user['profile']['lastName'], 'role': user['role'], 'mfa_enabled': user['security']['mfaEnabled'], 'created_at': user['metadata']['createdAt'], }
## Monitoring & Observability
### Metrics to Track
| Metric | Purpose | Alert Threshold |
|--------|---------|-----------------|
| `api.requests.v1.count` | v1 usage trends | N/A (informational) |
| `api.requests.v2.count` | v2 adoption rate | <10% after 2 months |
| `api.errors.v1.rate` | v1 error rate | >5% |
| `api.errors.v2.rate` | v2 error rate | >2% |
| `api.latency.v1.p95` | v1 performance | >500ms |
| `api.latency.v2.p95` | v2 performance | >500ms |
### Client Migration Dashboard
Track migration progress by client:
SELECT client_id, SUM(CASE WHEN api_version = 'v1' THEN 1 ELSE 0 END) as v1_requests, SUM(CASE WHEN api_version = 'v2' THEN 1 ELSE 0 END) as v2_requests, (v2_requests / (v1_requests + v2_requests)) * 100 as migration_percentage FROM api_requests WHERE timestamp > NOW() - INTERVAL '7 days' GROUP BY client_id ORDER BY migration_percentage ASC;
## Rollback Plan
If critical issues arise in v2:
1. **Immediate**: Extend sunset date by 3 months
2. **Week 1**: Fix v2 issues
3. **Week 2**: Deploy fixes to v2
4. **Week 3**: Resume migration communications
5. **Month 2**: Resume deprecation timeline
## Communication Plan
### Announcement Schedule
| Date | Channel | Message |
|------|---------|---------|
| 2024-01-15 | Email, Blog | v2 preview announcement |
| 2024-02-01 | Email, Blog, In-App | v2 released, v1 deprecation notice |
| 2024-03-01 | Email | 5 months until v1 sunset |
| 2024-05-01 | Email, In-App | 3 months until v1 sunset, warning phase starts |
| 2024-07-01 | Email, In-App | 1 month until v1 sunset, final warning |
| 2024-08-01 | Email | v1 sunset complete |
### Stakeholder Communication
**For Product Teams**:
- Migration guide: https://api.example.com/docs/v1-to-v2-migration
- Breaking changes: https://api.example.com/docs/v2-breaking-changes
- Support channel: #api-migration-support
**For Management**:
- Migration dashboard: https://dashboard.example.com/api-migration
- Risk assessment: [Link to risk document]
- Cost analysis: [Link to cost document]
## Success Criteria
| Criterion | Target | Measurement |
|-----------|--------|-------------|
| v2 adoption rate | >90% by Month 4 | % of requests to v2 endpoints |
| v1 error rate | <1% during deprecation | Error rate on v1 endpoints |
| v2 error rate | <2% after launch | Error rate on v2 endpoints |
| Migration support tickets | <50 total | Support ticket count |
| Client satisfaction | >4.0/5.0 | Post-migration survey |
## OpenAPI Specifications
### v1 Endpoint
/v1/users/{userId}: get: deprecated: true x-sunset-date: "2024-08-01T00:00:00Z" responses: '200': description: User retrieved (DEPRECATED) headers: Deprecation: schema: type: boolean example: true Sunset: schema: type: string format: date-time example: "Wed, 01 Aug 2024 00:00:00 GMT" Link: schema: type: string example: 'https://api.example.com/docs/v1-to-v2-migration; rel="deprecation"'
### v2 Endpoint
/v2/users/{userId}: get: summary: Get user by ID responses: '200': description: User retrieved successfully content: application/json: schema: $ref: '#/components/schemas/UserV2'
## References
- RFC 8594: Sunset HTTP Header
- Semantic Versioning 2.0.0
- [Internal] API Governance Policy
- [Internal] Deprecation Process GuidelinesWhy This Is Good:
- Comprehensive strategy: Covers technical, communication, monitoring, and rollback aspects of API versioning
- Clear migration path: Provides concrete examples in multiple languages showing before/after code patterns
- Deprecation best practices: Uses standard HTTP headers (Deprecation, Sunset, Link) per RFC 8594
- Realistic timeline: 6-month deprecation period with clear milestones and stakeholder communication plan
- Measurable success: Defines specific metrics and success criteria to track migration progress
- Backward compatibility: Dual-mode server approach allows gradual migration without breaking existing clients
- Risk mitigation: Includes rollback plan, monitoring dashboard, and support communication channels