omgkit 2.0.6 → 2.1.0

package/plugin/skills/backend/api-architecture/SKILL.md

@@ -0,0 +1,857 @@
+---
+name: api-architecture
+description: Enterprise API design with REST, GraphQL, gRPC patterns including versioning, pagination, and error handling
+category: backend
+triggers:
+  - api architecture
+  - api design
+  - rest api
+  - graphql
+  - grpc
+  - api versioning
+  - pagination
+---
+
+# API Architecture
+
+Enterprise-grade **API design patterns** following BigTech standards. This skill covers REST, GraphQL, and gRPC design with versioning, pagination, rate limiting, and comprehensive error handling.
+
+## Purpose
+
+Design APIs that scale and delight developers:
+
+- Apply REST best practices consistently
+- Implement GraphQL for flexible queries
+- Design gRPC for high-performance services
+- Handle versioning without breaking clients
+- Implement robust pagination patterns
+- Create comprehensive error responses
+
+## Features
+
+### 1. RESTful API Design
+
+```typescript
+// Express router with best practices
+import express from 'express';
+import { z } from 'zod';
+
+const router = express.Router();
+
+// Resource naming conventions
+// ✓ /users (collection)
+// ✓ /users/:id (resource)
+// ✓ /users/:id/posts (sub-collection)
+// ✗ /getUsers, /createUser (verbs in URL)
+
+// GET /api/v1/users - List users with pagination
+const ListUsersSchema = z.object({
+  page: z.coerce.number().min(1).default(1),
+  limit: z.coerce.number().min(1).max(100).default(20),
+  sort: z.enum(['created_at', 'name', 'email']).default('created_at'),
+  order: z.enum(['asc', 'desc']).default('desc'),
+  status: z.enum(['active', 'inactive', 'all']).optional(),
+});
+
+router.get('/users', async (req, res) => {
+  const query = ListUsersSchema.parse(req.query);
+
+  const { users, total } = await userService.list(query);
+
+  // Consistent response envelope
+  res.json({
+    data: users,
+    pagination: {
+      page: query.page,
+      limit: query.limit,
+      total,
+      totalPages: Math.ceil(total / query.limit),
+      hasMore: query.page * query.limit < total,
+    },
+    links: {
+      self: `/api/v1/users?page=${query.page}&limit=${query.limit}`,
+      first: `/api/v1/users?page=1&limit=${query.limit}`,
+      last: `/api/v1/users?page=${Math.ceil(total / query.limit)}&limit=${query.limit}`,
+      next: query.page * query.limit < total
+        ? `/api/v1/users?page=${query.page + 1}&limit=${query.limit}`
+        : null,
+      prev: query.page > 1
+        ? `/api/v1/users?page=${query.page - 1}&limit=${query.limit}`
+        : null,
+    },
+  });
+});
+
+// GET /api/v1/users/:id - Get single user
+router.get('/users/:id', async (req, res) => {
+  const user = await userService.findById(req.params.id);
+
+  if (!user) {
+    return res.status(404).json({
+      error: {
+        code: 'USER_NOT_FOUND',
+        message: 'User not found',
+        details: { id: req.params.id },
+      },
+    });
+  }
+
+  res.json({ data: user });
+});
+
+// POST /api/v1/users - Create user
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+  password: z.string().min(8),
+  role: z.enum(['user', 'admin']).default('user'),
+});
+
+router.post('/users', async (req, res) => {
+  const data = CreateUserSchema.parse(req.body);
+
+  const user = await userService.create(data);
+
+  // Return 201 with Location header
+  res.status(201)
+    .location(`/api/v1/users/${user.id}`)
+    .json({ data: user });
+});
+
+// PATCH /api/v1/users/:id - Partial update
+const UpdateUserSchema = CreateUserSchema.partial().omit({ password: true });
+
+router.patch('/users/:id', async (req, res) => {
+  const data = UpdateUserSchema.parse(req.body);
+
+  const user = await userService.update(req.params.id, data);
+
+  if (!user) {
+    return res.status(404).json({
+      error: { code: 'USER_NOT_FOUND', message: 'User not found' },
+    });
+  }
+
+  res.json({ data: user });
+});
+
+// DELETE /api/v1/users/:id - Delete user
+router.delete('/users/:id', async (req, res) => {
+  const deleted = await userService.delete(req.params.id);
+
+  if (!deleted) {
+    return res.status(404).json({
+      error: { code: 'USER_NOT_FOUND', message: 'User not found' },
+    });
+  }
+
+  res.status(204).send();
+});
+```
+
+### 2. Error Handling Standards
+
+```typescript
+// Standard error response format
+interface APIError {
+  code: string;           // Machine-readable error code
+  message: string;        // Human-readable message
+  details?: unknown;      // Additional context
+  requestId?: string;     // For debugging
+  documentation?: string; // Link to docs
+}
+
+// HTTP status codes mapping
+const ERROR_STATUS_MAP: Record<string, number> = {
+  VALIDATION_ERROR: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  RATE_LIMITED: 429,
+  INTERNAL_ERROR: 500,
+  SERVICE_UNAVAILABLE: 503,
+};
+
+// Error class hierarchy
+class APIException extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public details?: unknown,
+    public statusCode: number = ERROR_STATUS_MAP[code] || 500
+  ) {
+    super(message);
+    this.name = 'APIException';
+  }
+
+  toJSON(): APIError {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+    };
+  }
+}
+
+class ValidationException extends APIException {
+  constructor(errors: z.ZodError) {
+    super(
+      'VALIDATION_ERROR',
+      'Request validation failed',
+      errors.errors.map(e => ({
+        field: e.path.join('.'),
+        message: e.message,
+        code: e.code,
+      })),
+      400
+    );
+  }
+}
+
+class NotFoundException extends APIException {
+  constructor(resource: string, id: string) {
+    super(
+      'NOT_FOUND',
+      `${resource} not found`,
+      { resource, id },
+      404
+    );
+  }
+}
+
+// Global error handler
+function errorHandler(
+  err: Error,
+  req: express.Request,
+  res: express.Response,
+  next: express.NextFunction
+) {
+  const requestId = req.headers['x-request-id'] as string;
+
+  // Log error
+  logger.error({
+    requestId,
+    error: err.message,
+    stack: err.stack,
+    path: req.path,
+    method: req.method,
+  });
+
+  if (err instanceof APIException) {
+    return res.status(err.statusCode).json({
+      error: {
+        ...err.toJSON(),
+        requestId,
+      },
+    });
+  }
+
+  if (err instanceof z.ZodError) {
+    return res.status(400).json({
+      error: new ValidationException(err).toJSON(),
+    });
+  }
+
+  // Internal errors - don't leak details
+  res.status(500).json({
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'An unexpected error occurred',
+      requestId,
+    },
+  });
+}
+```
+
+### 3. API Versioning
+
+```typescript
+// URL versioning (recommended)
+// /api/v1/users
+// /api/v2/users
+
+// Version router
+const v1Router = express.Router();
+const v2Router = express.Router();
+
+// V1 response format
+v1Router.get('/users/:id', async (req, res) => {
+  const user = await userService.findById(req.params.id);
+  res.json(user); // Direct response
+});
+
+// V2 response format (with envelope)
+v2Router.get('/users/:id', async (req, res) => {
+  const user = await userService.findById(req.params.id);
+  res.json({
+    data: user,
+    meta: { version: 'v2' },
+  });
+});
+
+app.use('/api/v1', v1Router);
+app.use('/api/v2', v2Router);
+
+// Header versioning alternative
+function versionMiddleware(req: Request, res: Response, next: NextFunction) {
+  const version = req.headers['api-version'] || req.headers['accept-version'] || 'v1';
+  req.apiVersion = version;
+  next();
+}
+
+// Content negotiation
+app.get('/users/:id', (req, res) => {
+  const user = await userService.findById(req.params.id);
+
+  if (req.apiVersion === 'v2') {
+    return res.json({ data: user });
+  }
+
+  res.json(user);
+});
+
+// Sunset header for deprecation
+router.use('/v1/*', (req, res, next) => {
+  res.set('Sunset', 'Sat, 31 Dec 2025 23:59:59 GMT');
+  res.set('Deprecation', 'true');
+  res.set('Link', '</api/v2>; rel="successor-version"');
+  next();
+});
+```
+
+### 4. Rate Limiting
+
+```typescript
+import rateLimit from 'express-rate-limit';
+import RedisStore from 'rate-limit-redis';
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+// Basic rate limiter
+const basicLimiter = rateLimit({
+  windowMs: 60 * 1000, // 1 minute
+  max: 100, // 100 requests per minute
+  standardHeaders: true, // Return rate limit info in headers
+  legacyHeaders: false,
+  store: new RedisStore({
+    sendCommand: (...args: string[]) => redis.call(...args),
+  }),
+  handler: (req, res) => {
+    res.status(429).json({
+      error: {
+        code: 'RATE_LIMITED',
+        message: 'Too many requests',
+        retryAfter: res.getHeader('Retry-After'),
+      },
+    });
+  },
+});
+
+// Tiered rate limiting based on subscription
+function createTieredLimiter(tier: 'free' | 'pro' | 'enterprise') {
+  const limits = {
+    free: { windowMs: 60000, max: 60 },
+    pro: { windowMs: 60000, max: 600 },
+    enterprise: { windowMs: 60000, max: 6000 },
+  };
+
+  return rateLimit({
+    ...limits[tier],
+    keyGenerator: (req) => `${tier}:${req.user?.id || req.ip}`,
+    store: new RedisStore({ sendCommand: (...args) => redis.call(...args) }),
+  });
+}
+
+// Per-endpoint rate limiting
+const strictLimiter = rateLimit({
+  windowMs: 60 * 1000,
+  max: 10,
+  message: { error: { code: 'RATE_LIMITED', message: 'Rate limit exceeded for this endpoint' } },
+});
+
+router.post('/auth/login', strictLimiter, loginHandler);
+
+// Sliding window with Redis
+async function slidingWindowRateLimit(
+  key: string,
+  limit: number,
+  windowSeconds: number
+): Promise<{ allowed: boolean; remaining: number; resetAt: number }> {
+  const now = Date.now();
+  const windowStart = now - windowSeconds * 1000;
+
+  const multi = redis.multi();
+
+  // Remove old entries
+  multi.zremrangebyscore(key, 0, windowStart);
+  // Add current request
+  multi.zadd(key, now.toString(), `${now}-${Math.random()}`);
+  // Count requests in window
+  multi.zcard(key);
+  // Set expiry
+  multi.expire(key, windowSeconds);
+
+  const results = await multi.exec();
+  const count = results?.[2]?.[1] as number;
+
+  return {
+    allowed: count <= limit,
+    remaining: Math.max(0, limit - count),
+    resetAt: Math.ceil((windowStart + windowSeconds * 1000) / 1000),
+  };
+}
+```
+
+### 5. GraphQL Schema Design
+
+```typescript
+import { makeExecutableSchema } from '@graphql-tools/schema';
+
+const typeDefs = `#graphql
+  type Query {
+    user(id: ID!): User
+    users(
+      first: Int
+      after: String
+      filter: UserFilter
+      orderBy: UserOrderBy
+    ): UserConnection!
+  }
+
+  type Mutation {
+    createUser(input: CreateUserInput!): CreateUserPayload!
+    updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
+    deleteUser(id: ID!): DeleteUserPayload!
+  }
+
+  # Relay-style 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
+  }
+
+  type User {
+    id: ID!
+    email: String!
+    name: String!
+    status: UserStatus!
+    createdAt: DateTime!
+    updatedAt: DateTime!
+    posts(first: Int, after: String): PostConnection!
+  }
+
+  enum UserStatus {
+    ACTIVE
+    INACTIVE
+    SUSPENDED
+  }
+
+  input UserFilter {
+    status: UserStatus
+    search: String
+    createdAfter: DateTime
+    createdBefore: DateTime
+  }
+
+  input UserOrderBy {
+    field: UserOrderField!
+    direction: OrderDirection!
+  }
+
+  enum UserOrderField {
+    CREATED_AT
+    NAME
+    EMAIL
+  }
+
+  enum OrderDirection {
+    ASC
+    DESC
+  }
+
+  # Input types for mutations
+  input CreateUserInput {
+    email: String!
+    name: String!
+    password: String!
+  }
+
+  # Payload types for mutations
+  type CreateUserPayload {
+    user: User
+    errors: [UserError!]
+  }
+
+  type UserError {
+    field: String!
+    message: String!
+    code: String!
+  }
+
+  scalar DateTime
+`;
+
+const resolvers = {
+  Query: {
+    user: async (_, { id }, ctx) => {
+      return ctx.loaders.user.load(id);
+    },
+
+    users: async (_, args, ctx) => {
+      const { first = 20, after, filter, orderBy } = args;
+
+      const { users, total, hasMore } = await userService.list({
+        limit: first,
+        cursor: after ? decodeCursor(after) : undefined,
+        filter,
+        orderBy,
+      });
+
+      const edges = users.map(user => ({
+        cursor: encodeCursor(user.id),
+        node: user,
+      }));
+
+      return {
+        edges,
+        totalCount: total,
+        pageInfo: {
+          hasNextPage: hasMore,
+          hasPreviousPage: !!after,
+          startCursor: edges[0]?.cursor,
+          endCursor: edges[edges.length - 1]?.cursor,
+        },
+      };
+    },
+  },
+
+  Mutation: {
+    createUser: async (_, { input }, ctx) => {
+      try {
+        const user = await userService.create(input);
+        return { user, errors: [] };
+      } catch (error) {
+        return {
+          user: null,
+          errors: [{ field: 'email', message: error.message, code: 'VALIDATION_ERROR' }],
+        };
+      }
+    },
+  },
+
+  User: {
+    posts: async (user, args, ctx) => {
+      return ctx.loaders.userPosts.load({ userId: user.id, ...args });
+    },
+  },
+};
+
+// DataLoader for N+1 prevention
+import DataLoader from 'dataloader';
+
+function createLoaders() {
+  return {
+    user: new DataLoader(async (ids: string[]) => {
+      const users = await userService.findByIds(ids);
+      return ids.map(id => users.find(u => u.id === id));
+    }),
+
+    userPosts: new DataLoader(async (keys) => {
+      // Batch load posts for multiple users
+      const userIds = keys.map(k => k.userId);
+      const posts = await postService.findByUserIds(userIds);
+
+      return keys.map(key =>
+        posts.filter(p => p.userId === key.userId)
+      );
+    }),
+  };
+}
+```
+
+### 6. OpenAPI Specification
+
+```yaml
+openapi: 3.1.0
+info:
+  title: User API
+  version: 1.0.0
+  description: User management API
+  contact:
+    email: api@example.com
+  license:
+    name: MIT
+
+servers:
+  - url: https://api.example.com/v1
+    description: Production
+  - url: https://staging-api.example.com/v1
+    description: Staging
+
+paths:
+  /users:
+    get:
+      summary: List users
+      operationId: listUsers
+      tags: [Users]
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+        - name: status
+          in: query
+          schema:
+            $ref: '#/components/schemas/UserStatus'
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/User'
+                  pagination:
+                    $ref: '#/components/schemas/Pagination'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+    post:
+      summary: Create user
+      operationId: createUser
+      tags: [Users]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserInput'
+      responses:
+        '201':
+          description: User created
+          headers:
+            Location:
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    $ref: '#/components/schemas/User'
+
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email, name, status, createdAt]
+      properties:
+        id:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+        status:
+          $ref: '#/components/schemas/UserStatus'
+        createdAt:
+          type: string
+          format: date-time
+
+    UserStatus:
+      type: string
+      enum: [active, inactive, suspended]
+
+    CreateUserInput:
+      type: object
+      required: [email, name, password]
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          minLength: 2
+          maxLength: 100
+        password:
+          type: string
+          minLength: 8
+
+    Pagination:
+      type: object
+      properties:
+        page:
+          type: integer
+        limit:
+          type: integer
+        total:
+          type: integer
+        totalPages:
+          type: integer
+        hasMore:
+          type: boolean
+
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string
+        details:
+          type: object
+
+  responses:
+    BadRequest:
+      description: Bad request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                $ref: '#/components/schemas/Error'
+
+    Unauthorized:
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                $ref: '#/components/schemas/Error'
+
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - bearerAuth: []
+```
+
+## Use Cases
+
+### 1. Public API Design
+
+```typescript
+// Design for external developers
+router.get('/products', async (req, res) => {
+  // Always include request ID for support
+  const requestId = req.headers['x-request-id'] || generateRequestId();
+  res.set('X-Request-ID', requestId);
+
+  // Rate limit headers
+  res.set('X-RateLimit-Limit', '1000');
+  res.set('X-RateLimit-Remaining', String(remaining));
+  res.set('X-RateLimit-Reset', String(resetTime));
+
+  // Response
+  res.json({
+    data: products,
+    pagination: { ... },
+    meta: {
+      requestId,
+      apiVersion: 'v1',
+    },
+  });
+});
+```
+
+### 2. Internal Microservice API
+
+```typescript
+// gRPC for internal services
+// proto/user.proto
+syntax = "proto3";
+
+package user;
+
+service UserService {
+  rpc GetUser(GetUserRequest) returns (User);
+  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
+  rpc CreateUser(CreateUserRequest) returns (User);
+}
+
+message User {
+  string id = 1;
+  string email = 2;
+  string name = 3;
+  UserStatus status = 4;
+}
+
+enum UserStatus {
+  UNKNOWN = 0;
+  ACTIVE = 1;
+  INACTIVE = 2;
+}
+```
+
+## Best Practices
+
+### Do's
+
+- **Use consistent naming** - Plural nouns for collections
+- **Return appropriate status codes** - 201 for create, 204 for delete
+- **Include request IDs** - For debugging and support
+- **Document everything** - OpenAPI/Swagger specs
+- **Version from day one** - Avoid breaking changes
+- **Implement idempotency** - For POST/PUT operations
+
+### Don'ts
+
+- Don't use verbs in URLs
+- Don't return 200 for errors
+- Don't expose internal errors
+- Don't skip pagination
+- Don't ignore cache headers
+- Don't forget rate limiting
+
+## Related Skills
+
+- **backend-development** - Implementation patterns
+- **security** - API security
+- **caching-strategies** - Response caching
+
+## Reference Resources
+
+- [REST API Design](https://restfulapi.net/)
+- [GraphQL Best Practices](https://graphql.org/learn/best-practices/)
+- [Google API Design Guide](https://cloud.google.com/apis/design)
+- [Microsoft REST Guidelines](https://github.com/microsoft/api-guidelines)