codingbuddy-rules 2.0.0 → 2.2.0

package/.ai-rules/skills/api-design/SKILL.md

@@ -0,0 +1,459 @@
+---
+name: api-design
+description: Use when designing REST or GraphQL APIs - covers OpenAPI spec, resource design, versioning, and documentation
+---
+
+# API Design
+
+## Overview
+
+Design APIs that are consistent, predictable, and well-documented. This skill covers REST and GraphQL API design patterns.
+
+**Core principle:** APIs are contracts. Once published, breaking changes are expensive.
+
+## When to Use
+
+**Use this skill:**
+- Designing new API endpoints
+- Refactoring existing APIs
+- Adding versioning strategy
+- Creating OpenAPI/GraphQL specifications
+- Standardizing error responses
+
+**Not needed for:**
+- Internal function signatures
+- Database schema design (use data-engineer agent)
+
+## REST API Design
+
+### Resource Naming
+
+```
+✅ Good                          ❌ Bad
+-----------------------------------------
+GET  /users                      GET  /getUsers
+GET  /users/{id}                 GET  /user?id=123
+POST /users                      POST /createUser
+PUT  /users/{id}                 POST /updateUser
+DELETE /users/{id}               GET  /deleteUser/{id}
+GET  /users/{id}/orders          GET  /getUserOrders
+```
+
+**Rules:**
+- Use nouns, not verbs (HTTP method is the verb)
+- Plural for collections: `/users` not `/user`
+- Hierarchical for relationships: `/users/{id}/orders`
+- Lowercase, hyphen-separated: `/user-profiles` not `/userProfiles`
+
+### HTTP Methods
+
+| Method | Purpose | Idempotent | Safe |
+|--------|---------|------------|------|
+| GET | Retrieve resource | Yes | Yes |
+| POST | Create resource | No | No |
+| PUT | Replace resource | Yes | No |
+| PATCH | Partial update | Yes* | No |
+| DELETE | Remove resource | Yes | No |
+
+*PATCH is idempotent if using JSON Patch/Merge Patch format.
+
+### Status Codes
+
+```
+2xx Success
+-----------------------------------------
+200 OK              - GET/PUT/PATCH success, body contains data
+201 Created         - POST success, Location header has URL
+204 No Content      - DELETE success, no body
+
+4xx Client Error
+-----------------------------------------
+400 Bad Request     - Invalid input (validation failed)
+401 Unauthorized    - Authentication required
+403 Forbidden       - Authenticated but not allowed
+404 Not Found       - Resource doesn't exist
+409 Conflict        - State conflict (duplicate, version mismatch)
+422 Unprocessable   - Valid syntax but semantic error
+
+5xx Server Error
+-----------------------------------------
+500 Internal Error  - Unexpected server error
+502 Bad Gateway     - Upstream service failed
+503 Unavailable     - Temporary overload
+```
+
+### Standard Response Format
+
+**Success Response:**
+```json
+{
+  "data": {
+    "id": "123",
+    "name": "Example"
+  },
+  "meta": {
+    "requestId": "abc-123",
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+**Collection Response:**
+```json
+{
+  "data": [
+    { "id": "1", "name": "First" },
+    { "id": "2", "name": "Second" }
+  ],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "pageSize": 20,
+    "hasNext": true
+  }
+}
+```
+
+**Error Response:**
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input data",
+    "details": [
+      { "field": "email", "message": "Invalid email format" }
+    ]
+  },
+  "meta": {
+    "requestId": "abc-123",
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### Versioning Strategies
+
+| Strategy | Example | Pros | Cons |
+|----------|---------|------|------|
+| URI Path | `/v1/users` | Clear, cacheable | URL changes |
+| Header | `Accept: application/vnd.api+json;version=1` | Clean URLs | Hidden |
+| Query Param | `/users?version=1` | Easy to test | Pollutes params |
+
+**Recommended:** URI Path versioning for simplicity and clarity.
+
+```
+/v1/users           # Version 1
+/v2/users           # Version 2 (breaking changes)
+```
+
+**When to increment version:**
+- Removing fields
+- Changing field types
+- Renaming fields
+- Changing behavior
+
+**Non-breaking (no version bump):**
+- Adding new optional fields
+- Adding new endpoints
+- Adding new optional parameters
+
+### OpenAPI Specification
+
+```yaml
+openapi: 3.1.0
+info:
+  title: User API
+  version: 1.0.0
+  description: User management endpoints
+
+paths:
+  /users:
+    get:
+      summary: List users
+      operationId: listUsers
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: pageSize
+          in: query
+          schema:
+            type: integer
+            default: 20
+            maximum: 100
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserListResponse'
+    post:
+      summary: Create user
+      operationId: createUser
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserRequest'
+      responses:
+        '201':
+          description: Created
+          headers:
+            Location:
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserResponse'
+        '400':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+components:
+  schemas:
+    User:
+      type: object
+      required:
+        - id
+        - email
+      properties:
+        id:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+
+    ErrorResponse:
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          type: object
+          required:
+            - code
+            - message
+          properties:
+            code:
+              type: string
+            message:
+              type: string
+            details:
+              type: array
+              items:
+                type: object
+                properties:
+                  field:
+                    type: string
+                  message:
+                    type: string
+```
+
+## GraphQL API Design
+
+### Schema Design
+
+```graphql
+type Query {
+  user(id: ID!): User
+  users(filter: UserFilter, pagination: Pagination): UserConnection!
+}
+
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
+  deleteUser(id: ID!): DeleteUserPayload!
+}
+
+type User {
+  id: ID!
+  email: String!
+  name: String
+  orders(first: Int, after: String): OrderConnection!
+  createdAt: DateTime!
+}
+
+# Relay-style connection for pagination
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type UserEdge {
+  cursor: String!
+  node: User!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+# Input types
+input CreateUserInput {
+  email: String!
+  name: String
+}
+
+# Payload types with union for errors
+type CreateUserPayload {
+  user: User
+  errors: [UserError!]
+}
+
+type UserError {
+  field: String
+  message: String!
+  code: String!
+}
+```
+
+### N+1 Query Prevention
+
+```typescript
+// ❌ Bad: N+1 queries
+const resolvers = {
+  User: {
+    orders: async (user) => {
+      // Called once per user - N queries
+      return db.orders.findByUserId(user.id);
+    }
+  }
+};
+
+// ✅ Good: DataLoader batching
+import DataLoader from 'dataloader';
+
+const orderLoader = new DataLoader(async (userIds) => {
+  // Single batched query
+  const orders = await db.orders.findByUserIds(userIds);
+  return userIds.map(id => orders.filter(o => o.userId === id));
+});
+
+const resolvers = {
+  User: {
+    orders: async (user) => orderLoader.load(user.id)
+  }
+};
+```
+
+### Query Complexity Limiting
+
+```typescript
+// Prevent expensive queries
+const complexityConfig = {
+  maximumComplexity: 1000,
+  scalarCost: 1,
+  objectCost: 10,
+  listFactor: 10, // Multiply by list size
+};
+
+// Example: users(first: 100) { orders(first: 50) { ... } }
+// Complexity: 10 + (100 * (10 + (50 * 10))) = 51,010 (rejected)
+```
+
+## Rate Limiting
+
+### Headers
+
+```http
+HTTP/1.1 200 OK
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1704067200
+
+# When exceeded
+HTTP/1.1 429 Too Many Requests
+Retry-After: 60
+```
+
+### Strategies
+
+| Strategy | Description | Use Case |
+|----------|-------------|----------|
+| Fixed Window | X requests per minute | Simple APIs |
+| Sliding Window | Rolling window | More accurate |
+| Token Bucket | Refill tokens over time | Burst-friendly |
+| Leaky Bucket | Constant output rate | Smooth traffic |
+
+## API Gateway Patterns
+
+```
+Client → API Gateway → Microservices
+              ↓
+      - Authentication
+      - Rate Limiting
+      - Request Routing
+      - Response Caching
+      - Request/Response Transform
+      - Circuit Breaker
+```
+
+## Documentation Checklist
+
+Before shipping an API:
+
+- [ ] OpenAPI/GraphQL schema complete
+- [ ] All error codes documented
+- [ ] Authentication described
+- [ ] Rate limits documented
+- [ ] Example requests/responses
+- [ ] Changelog for versions
+- [ ] SDK/client libraries linked
+- [ ] Postman/Insomnia collection
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Verbs in URLs | Use nouns: `/users` not `/getUsers` |
+| Inconsistent naming | Pick one: camelCase or snake_case |
+| Missing pagination | Always paginate lists |
+| No error codes | Use machine-readable codes |
+| Breaking changes | Version the API |
+| Missing rate limits | Protect against abuse |
+| N+1 in GraphQL | Use DataLoader |
+| No request IDs | Add for debugging |
+
+## Quick Reference
+
+```
+REST
+────────────────────────────────────
+GET    /resources          List all
+GET    /resources/{id}     Get one
+POST   /resources          Create
+PUT    /resources/{id}     Replace
+PATCH  /resources/{id}     Update
+DELETE /resources/{id}     Remove
+
+GraphQL
+────────────────────────────────────
+Query       Read operations
+Mutation    Write operations
+Subscription Real-time updates
+
+Connections (Relay)
+────────────────────────────────────
+edges       List of edge objects
+node        The actual object
+cursor      Pagination cursor
+pageInfo    hasNextPage, etc.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codingbuddy-rules",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "AI coding rules for consistent practices across AI assistants",
   "main": "index.js",
   "types": "index.d.ts",