locus-product-planning 1.1.0 → 1.2.1

package/skills/04-developer-specializations/core/api-designer/SKILL.md

@@ -0,0 +1,579 @@
+---
+name: api-designer
+description: REST and GraphQL API design, versioning strategies, documentation, and building developer-friendly interfaces
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: core
+  council: code-review-council
+---
+
+# API Designer
+
+You embody the perspective of a senior API designer with expertise in creating intuitive, well-documented, and developer-friendly APIs that stand the test of time.
+
+## When to Apply
+
+Invoke this skill when:
+- Designing new APIs (REST, GraphQL, gRPC)
+- Reviewing API designs for consistency
+- Planning API versioning strategies
+- Writing API documentation
+- Designing error handling and response formats
+- Creating API security patterns
+- Building SDK-friendly interfaces
+- Planning backwards-compatible changes
+
+## Core Competencies
+
+### 1. API Design
+- Resource modeling and naming
+- HTTP method semantics
+- Response format consistency
+- Error handling patterns
+
+### 2. Documentation
+- OpenAPI/Swagger specifications
+- Interactive documentation
+- Code examples and SDKs
+- Changelog management
+
+### 3. Versioning
+- Breaking vs non-breaking changes
+- Deprecation strategies
+- Migration support
+- Multiple version maintenance
+
+### 4. Security
+- Authentication patterns
+- Authorization design
+- Rate limiting
+- Input validation
+
+## REST API Design
+
+### Resource Naming Conventions
+
+| Pattern | Example | Description |
+|---------|---------|-------------|
+| **Collection** | `/users` | List of resources |
+| **Instance** | `/users/123` | Single resource |
+| **Sub-resource** | `/users/123/orders` | Related collection |
+| **Action** | `/users/123/activate` | Non-CRUD operation |
+
+### Naming Rules
+- Use nouns, not verbs (except actions)
+- Use plural for collections
+- Use kebab-case for multi-word
+- Avoid deep nesting (max 2-3 levels)
+
+```
+Good:
+  GET  /users
+  GET  /users/123
+  GET  /users/123/orders
+  POST /users/123/reset-password
+
+Bad:
+  GET  /getUsers
+  GET  /user/123  (inconsistent plural)
+  GET  /users/123/orders/456/items/789/details (too deep)
+```
+
+### HTTP Methods
+
+| Method | Use | Idempotent | Safe |
+|--------|-----|------------|------|
+| **GET** | Read resource(s) | Yes | Yes |
+| **POST** | Create resource | No | No |
+| **PUT** | Replace resource | Yes | No |
+| **PATCH** | Partial update | No* | No |
+| **DELETE** | Remove resource | Yes | No |
+
+*PATCH can be idempotent with proper design
+
+### Status Codes
+
+| Range | Meaning | Common Codes |
+|-------|---------|--------------|
+| **2xx** | Success | 200 OK, 201 Created, 204 No Content |
+| **3xx** | Redirect | 301 Moved, 304 Not Modified |
+| **4xx** | Client error | 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable |
+| **5xx** | Server error | 500 Internal Error, 502 Bad Gateway, 503 Unavailable |
+
+### Status Code Decision Tree
+
+```
+Success?
+├─ Yes → Resource returned?
+│        ├─ Yes → 200 OK
+│        └─ No  → Created?
+│                 ├─ Yes → 201 Created
+│                 └─ No  → 204 No Content
+│
+└─ No → Client's fault?
+        ├─ Yes → Auth issue?
+        │        ├─ Yes → Needs login? → 401 Unauthorized
+        │        │        └─ Has access? → 403 Forbidden
+        │        └─ No  → Resource exists?
+        │                 ├─ No  → 404 Not Found
+        │                 └─ Yes → Valid input?
+        │                          ├─ No  → 400 Bad Request (syntax)
+        │                          │        422 Unprocessable (semantic)
+        │                          └─ Yes → 409 Conflict (state)
+        │
+        └─ No (Server's fault) → 500/502/503
+```
+
+## Response Format
+
+### Standard Response Structure
+
+```json
+// Success response
+{
+  "data": {
+    "id": "user_123",
+    "type": "user",
+    "attributes": {
+      "email": "user@example.com",
+      "name": "John Doe",
+      "created_at": "2024-01-15T10:30:00Z"
+    },
+    "relationships": {
+      "organization": {
+        "id": "org_456",
+        "type": "organization"
+      }
+    }
+  },
+  "meta": {
+    "request_id": "req_abc123"
+  }
+}
+
+// Collection response
+{
+  "data": [...],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "per_page": 20,
+    "request_id": "req_abc123"
+  },
+  "links": {
+    "self": "/users?page=1",
+    "next": "/users?page=2",
+    "last": "/users?page=5"
+  }
+}
+```
+
+### Error Response Structure
+
+```json
+{
+  "error": {
+    "code": "validation_error",
+    "message": "The request contains invalid parameters",
+    "details": [
+      {
+        "field": "email",
+        "code": "invalid_format",
+        "message": "Must be a valid email address"
+      },
+      {
+        "field": "age",
+        "code": "out_of_range",
+        "message": "Must be between 18 and 120"
+      }
+    ],
+    "request_id": "req_abc123",
+    "documentation_url": "https://api.example.com/docs/errors#validation_error"
+  }
+}
+```
+
+### Error Code Taxonomy
+
+```
+authentication_error    - Auth token invalid/expired
+authorization_error     - User lacks permission
+validation_error        - Input validation failed
+not_found              - Resource doesn't exist
+conflict               - Resource state conflict
+rate_limit_exceeded    - Too many requests
+internal_error         - Server error (hide details)
+service_unavailable    - Temporary outage
+```
+
+## Pagination
+
+### Cursor-Based (Recommended)
+
+```
+GET /orders?cursor=eyJpZCI6MTIzfQ&limit=20
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "has_more": true,
+    "next_cursor": "eyJpZCI6MTQzfQ"
+  }
+}
+```
+
+**Pros**: Stable with concurrent writes, no offset performance issues
+**Cons**: Can't jump to arbitrary page
+
+### Offset-Based
+
+```
+GET /orders?offset=40&limit=20
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "total": 500,
+    "offset": 40,
+    "limit": 20
+  }
+}
+```
+
+**Pros**: Simple, supports page jumping
+**Cons**: Unstable with writes, slow for large offsets
+
+## Filtering and Sorting
+
+### Filter Patterns
+
+```
+# Simple equality
+GET /users?status=active
+
+# Multiple values
+GET /users?status=active,pending
+
+# Comparison operators
+GET /orders?total[gte]=100&total[lte]=500
+
+# Date ranges
+GET /events?created_at[gte]=2024-01-01&created_at[lt]=2024-02-01
+
+# Search
+GET /products?q=laptop
+
+# Nested filters (if needed)
+GET /users?organization.plan=enterprise
+```
+
+### Sorting
+
+```
+# Single field
+GET /users?sort=created_at
+
+# Descending
+GET /users?sort=-created_at
+
+# Multiple fields
+GET /users?sort=-created_at,name
+```
+
+## Versioning Strategies
+
+### URL Path Versioning (Recommended)
+
+```
+GET /v1/users
+GET /v2/users
+```
+
+**Pros**: Explicit, easy to route, cache-friendly
+**Cons**: Not "pure" REST
+
+### Header Versioning
+
+```
+GET /users
+Accept: application/vnd.api+json; version=2
+```
+
+**Pros**: Clean URLs
+**Cons**: Hidden, harder to test, cache complexity
+
+### Version Lifecycle
+
+```
+v1 (deprecated) ─────────> sunset date ───────> removed
+v2 (current)    ─────────> stable ────────────> deprecated (when v3)
+v3 (preview)    ─────────> stable (becomes current)
+```
+
+### Breaking vs Non-Breaking Changes
+
+| Non-Breaking (Safe) | Breaking (Requires New Version) |
+|---------------------|----------------------------------|
+| Add optional field | Remove field |
+| Add new endpoint | Change field type |
+| Add optional parameter | Change field meaning |
+| Expand enum values | Remove enum value |
+| Relax validation | Tighten validation |
+| Add HTTP method | Change URL structure |
+
+## GraphQL Design
+
+### Schema Design
+
+```graphql
+type User {
+  id: ID!
+  email: String!
+  name: String!
+  createdAt: DateTime!
+  
+  # Relationships with pagination
+  orders(first: Int, after: String): OrderConnection!
+  
+  # Computed fields
+  totalSpent: Money!
+}
+
+type OrderConnection {
+  edges: [OrderEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type OrderEdge {
+  cursor: String!
+  node: Order!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+### Query Patterns
+
+```graphql
+# Good: Specific fields, connection pattern
+query GetUserOrders($userId: ID!, $first: Int!, $after: String) {
+  user(id: $userId) {
+    id
+    name
+    orders(first: $first, after: $after) {
+      edges {
+        node {
+          id
+          total
+          status
+        }
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+    }
+  }
+}
+
+# Avoid: Deeply nested queries without limits
+query Bad {
+  users {
+    orders {
+      items {
+        product {
+          reviews {
+            # This can explode
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Mutation Patterns
+
+```graphql
+# Input types for mutations
+input CreateUserInput {
+  email: String!
+  name: String!
+  organizationId: ID
+}
+
+# Consistent mutation response
+type CreateUserPayload {
+  user: User
+  errors: [UserError!]!
+}
+
+type UserError {
+  field: String
+  message: String!
+  code: ErrorCode!
+}
+
+mutation CreateUser($input: CreateUserInput!) {
+  createUser(input: $input) {
+    user {
+      id
+      email
+    }
+    errors {
+      field
+      message
+    }
+  }
+}
+```
+
+## API Security
+
+### Authentication
+
+| Method | Use Case |
+|--------|----------|
+| **API Keys** | Server-to-server, simple auth |
+| **OAuth 2.0 + OIDC** | User authorization, SSO |
+| **JWT** | Stateless session tokens |
+| **mTLS** | High-security B2B |
+
+### Authorization Header
+
+```
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+### Rate Limiting Headers
+
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 998
+X-RateLimit-Reset: 1640995200
+Retry-After: 60  (when limited)
+```
+
+### Input Validation Checklist
+
+- [ ] Validate content-type header
+- [ ] Limit request body size
+- [ ] Validate all input parameters
+- [ ] Sanitize strings for injection
+- [ ] Validate file uploads (type, size)
+- [ ] Prevent mass assignment
+
+## Documentation
+
+### OpenAPI Specification Structure
+
+```yaml
+openapi: 3.1.0
+info:
+  title: My API
+  version: 1.0.0
+  description: |
+    # Introduction
+    Welcome to the API documentation.
+    
+    ## Authentication
+    All requests require an API key...
+
+servers:
+  - url: https://api.example.com/v1
+    description: Production
+
+paths:
+  /users:
+    get:
+      summary: List users
+      operationId: listUsers
+      tags: [Users]
+      parameters:
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [active, inactive]
+      responses:
+        '200':
+          description: List of users
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserList'
+              examples:
+                default:
+                  $ref: '#/components/examples/UserListExample'
+```
+
+### Documentation Requirements
+
+- [ ] All endpoints documented
+- [ ] Request/response examples
+- [ ] Error responses documented
+- [ ] Authentication explained
+- [ ] Rate limits documented
+- [ ] Changelog maintained
+- [ ] Interactive playground
+
+## API Design Checklist
+
+### Before Building
+
+- [ ] Resources and relationships identified
+- [ ] URL structure consistent
+- [ ] HTTP methods appropriate
+- [ ] Response format standardized
+- [ ] Error format defined
+- [ ] Versioning strategy chosen
+- [ ] Authentication mechanism selected
+- [ ] Rate limiting planned
+
+### Before Releasing
+
+- [ ] OpenAPI spec complete
+- [ ] All endpoints tested
+- [ ] Error handling consistent
+- [ ] Security review complete
+- [ ] Performance benchmarked
+- [ ] Monitoring in place
+- [ ] Deprecation policy documented
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| Verbs in URLs | Use HTTP methods semantically |
+| Inconsistent naming | Establish conventions early |
+| Missing pagination | Always paginate collections |
+| Generic 500 errors | Proper status codes and messages |
+| No request IDs | Include for debugging |
+| Undocumented changes | Maintain changelog |
+| Breaking changes silently | Version and communicate |
+
+## Constraints
+
+- Always use HTTPS
+- Include request ID in all responses
+- Document all public endpoints
+- Version from day one
+- Never expose internal errors
+- Rate limit all endpoints
+- Validate all input
+
+## Related Skills
+
+- `backend-developer` - Implementation
+- `frontend-developer` - Consumer perspective
+- `security-engineer` - API security
+- `technical-writer` - Documentation