@mytechtoday/augment-extensions 0.1.0 → 0.1.2

package/augment-extensions/domain-rules/api-design/rules/graphql-api.md

@@ -0,0 +1,313 @@
+# GraphQL API Design
+
+Best practices for designing GraphQL APIs.
+
+## Schema Design
+
+Design clear, intuitive schemas.
+
+```graphql
+# Good - Clear type definitions
+type User {
+  id: ID!
+  name: String!
+  email: String!
+  role: UserRole!
+  createdAt: DateTime!
+  orders: [Order!]!
+}
+
+type Order {
+  id: ID!
+  user: User!
+  items: [OrderItem!]!
+  total: Float!
+  status: OrderStatus!
+  createdAt: DateTime!
+}
+
+enum UserRole {
+  ADMIN
+  USER
+  GUEST
+}
+
+enum OrderStatus {
+  PENDING
+  PROCESSING
+  SHIPPED
+  DELIVERED
+  CANCELLED
+}
+
+# Good - Input types for mutations
+input CreateUserInput {
+  name: String!
+  email: String!
+  role: UserRole = USER
+}
+
+input UpdateUserInput {
+  name: String
+  email: String
+  role: UserRole
+}
+```
+
+## Queries
+
+Design efficient, flexible queries.
+
+```graphql
+# Good - Root queries
+type Query {
+  # Single resource
+  user(id: ID!): User
+  
+  # Collection with filtering
+  users(
+    role: UserRole
+    status: UserStatus
+    limit: Int = 20
+    offset: Int = 0
+  ): UserConnection!
+  
+  # Search
+  searchUsers(query: String!): [User!]!
+  
+  # Nested resource
+  order(id: ID!): Order
+  orders(userId: ID, status: OrderStatus): [Order!]!
+}
+
+# Good - Connection pattern for pagination
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type UserEdge {
+  node: User!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+## Mutations
+
+Design clear, atomic mutations.
+
+```graphql
+# Good - Mutations with input types
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
+  deleteUser(id: ID!): DeleteUserPayload!
+  
+  createOrder(input: CreateOrderInput!): CreateOrderPayload!
+  updateOrderStatus(id: ID!, status: OrderStatus!): UpdateOrderPayload!
+}
+
+# Good - Payload types with errors
+type CreateUserPayload {
+  user: User
+  errors: [UserError!]!
+}
+
+type UserError {
+  field: String
+  message: String!
+  code: ErrorCode!
+}
+
+enum ErrorCode {
+  VALIDATION_ERROR
+  NOT_FOUND
+  UNAUTHORIZED
+  FORBIDDEN
+  INTERNAL_ERROR
+}
+
+# Bad - Multiple operations in one mutation
+type Mutation {
+  updateUserAndOrders(userId: ID!, userData: UpdateUserInput!, orderIds: [ID!]!): User
+}
+```
+
+## Subscriptions
+
+Design real-time subscriptions.
+
+```graphql
+# Good - Subscriptions for real-time updates
+type Subscription {
+  userCreated: User!
+  userUpdated(id: ID!): User!
+  orderStatusChanged(userId: ID!): Order!
+  
+  # With filtering
+  orderUpdated(status: OrderStatus): Order!
+}
+
+# Usage
+subscription {
+  orderStatusChanged(userId: "123") {
+    id
+    status
+    updatedAt
+  }
+}
+```
+
+## Field Naming
+
+Use consistent naming conventions.
+
+```graphql
+# Good - Consistent naming
+type User {
+  id: ID!              # Singular
+  firstName: String!   # camelCase
+  lastName: String!
+  emailAddress: String!
+  isActive: Boolean!   # Boolean prefix: is, has, can
+  hasOrders: Boolean!
+  createdAt: DateTime! # Timestamp suffix: At
+  updatedAt: DateTime!
+}
+
+# Bad - Inconsistent naming
+type User {
+  user_id: ID!         # snake_case (inconsistent)
+  first_name: String!
+  active: Boolean!     # Missing 'is' prefix
+  created: DateTime!   # Missing 'At' suffix
+}
+```
+
+## Error Handling
+
+Implement comprehensive error handling.
+
+```graphql
+# Good - Errors in payload
+type CreateUserPayload {
+  user: User
+  errors: [UserError!]!
+  success: Boolean!
+}
+
+# Good - Field-level errors
+type UserError {
+  field: String        # Which field caused the error
+  message: String!     # Human-readable message
+  code: ErrorCode!     # Machine-readable code
+}
+
+# Usage in resolver
+{
+  "data": {
+    "createUser": {
+      "user": null,
+      "errors": [
+        {
+          "field": "email",
+          "message": "Email is already taken",
+          "code": "VALIDATION_ERROR"
+        }
+      ],
+      "success": false
+    }
+  }
+}
+```
+
+## N+1 Problem
+
+Solve N+1 queries with DataLoader.
+
+```typescript
+// Good - Use DataLoader
+import DataLoader from 'dataloader';
+
+const userLoader = new DataLoader(async (userIds: string[]) => {
+  const users = await db.users.findMany({
+    where: { id: { in: userIds } }
+  });
+  
+  return userIds.map(id => users.find(u => u.id === id));
+});
+
+// Resolver
+const resolvers = {
+  Order: {
+    user: (order) => userLoader.load(order.userId)
+  }
+};
+
+// Bad - N+1 query
+const resolvers = {
+  Order: {
+    user: (order) => db.users.findOne({ id: order.userId })
+  }
+};
+```
+
+## Pagination
+
+Implement cursor-based pagination.
+
+```graphql
+# Good - Relay-style cursor pagination
+type Query {
+  users(
+    first: Int
+    after: String
+    last: Int
+    before: String
+  ): UserConnection!
+}
+
+# Usage
+query {
+  users(first: 10, after: "cursor123") {
+    edges {
+      node {
+        id
+        name
+      }
+      cursor
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **Use nullable fields carefully** - Only make required fields non-null
+2. **Design for clients** - Think about client use cases
+3. **Use input types** - For mutations
+4. **Use payload types** - Include errors in mutation responses
+5. **Solve N+1 problem** - Use DataLoader
+6. **Implement pagination** - Use cursor-based pagination
+7. **Version with fields** - Add new fields, deprecate old ones
+8. **Use enums** - For fixed sets of values
+9. **Document schema** - Use descriptions
+10. **Validate input** - Server-side validation
+11. **Implement auth** - Field-level authorization
+12. **Monitor performance** - Track query complexity
+13. **Use subscriptions** - For real-time updates
+14. **Keep mutations atomic** - One operation per mutation
+15. **Use consistent naming** - camelCase for fields
+

package/augment-extensions/domain-rules/api-design/rules/rest-api.md

@@ -0,0 +1,214 @@
+# RESTful API Design
+
+Best practices for designing RESTful APIs.
+
+## Resource Naming
+
+Use nouns for resources, not verbs.
+
+```
+# Good - Nouns
+GET    /users
+GET    /users/123
+POST   /users
+PUT    /users/123
+DELETE /users/123
+
+GET    /users/123/orders
+POST   /users/123/orders
+
+# Bad - Verbs
+GET    /getUsers
+POST   /createUser
+POST   /deleteUser/123
+```
+
+## HTTP Methods
+
+Use appropriate HTTP methods for operations.
+
+```
+GET    - Retrieve resource(s) (safe, idempotent)
+POST   - Create new resource (not idempotent)
+PUT    - Update/replace entire resource (idempotent)
+PATCH  - Partial update of resource (idempotent)
+DELETE - Remove resource (idempotent)
+HEAD   - Get headers only (safe, idempotent)
+OPTIONS - Get available methods (safe, idempotent)
+```
+
+## URL Structure
+
+Keep URLs simple, intuitive, and hierarchical.
+
+```
+# Good - Clear hierarchy
+GET /api/v1/users/123/orders/456/items
+
+# Good - Query parameters for filtering
+GET /api/v1/users?role=admin&status=active
+
+# Good - Pagination
+GET /api/v1/users?page=2&limit=20
+
+# Bad - Deep nesting
+GET /api/v1/users/123/orders/456/items/789/reviews/012
+
+# Bad - Actions in URL
+POST /api/v1/users/123/activate
+# Better: PATCH /api/v1/users/123 with {"status": "active"}
+```
+
+## HTTP Status Codes
+
+Use appropriate status codes.
+
+```
+# Success
+200 OK              - Successful GET, PUT, PATCH, DELETE
+201 Created         - Successful POST (resource created)
+204 No Content      - Successful DELETE (no response body)
+
+# Client Errors
+400 Bad Request     - Invalid request data
+401 Unauthorized    - Authentication required
+403 Forbidden       - Authenticated but not authorized
+404 Not Found       - Resource doesn't exist
+409 Conflict        - Resource conflict (e.g., duplicate)
+422 Unprocessable   - Validation errors
+429 Too Many Requests - Rate limit exceeded
+
+# Server Errors
+500 Internal Server Error - Server error
+502 Bad Gateway          - Upstream server error
+503 Service Unavailable  - Server temporarily unavailable
+```
+
+## Request/Response Format
+
+Use consistent JSON structure.
+
+```json
+// Good - GET /api/v1/users/123
+{
+  "id": "123",
+  "name": "John Doe",
+  "email": "john@example.com",
+  "createdAt": "2024-01-15T10:30:00Z",
+  "updatedAt": "2024-01-20T14:45:00Z"
+}
+
+// Good - POST /api/v1/users (request)
+{
+  "name": "Jane Smith",
+  "email": "jane@example.com",
+  "role": "admin"
+}
+
+// Good - POST /api/v1/users (response)
+{
+  "id": "124",
+  "name": "Jane Smith",
+  "email": "jane@example.com",
+  "role": "admin",
+  "createdAt": "2024-01-21T09:00:00Z"
+}
+
+// Good - Collection response
+{
+  "data": [
+    { "id": "123", "name": "John Doe" },
+    { "id": "124", "name": "Jane Smith" }
+  ],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "limit": 20,
+    "totalPages": 5
+  },
+  "links": {
+    "self": "/api/v1/users?page=1",
+    "next": "/api/v1/users?page=2",
+    "last": "/api/v1/users?page=5"
+  }
+}
+```
+
+## Error Responses
+
+Provide consistent, helpful error messages.
+
+```json
+// Good - Detailed error response
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Email is required"
+      },
+      {
+        "field": "age",
+        "message": "Age must be at least 18"
+      }
+    ],
+    "timestamp": "2024-01-21T10:00:00Z",
+    "path": "/api/v1/users"
+  }
+}
+
+// Good - Simple error
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "User not found",
+    "timestamp": "2024-01-21T10:00:00Z"
+  }
+}
+```
+
+## Filtering, Sorting, Pagination
+
+Support common query operations.
+
+```
+# Filtering
+GET /api/v1/users?role=admin&status=active
+
+# Sorting
+GET /api/v1/users?sort=name
+GET /api/v1/users?sort=-createdAt  # Descending
+
+# Pagination (offset-based)
+GET /api/v1/users?page=2&limit=20
+
+# Pagination (cursor-based)
+GET /api/v1/users?cursor=abc123&limit=20
+
+# Field selection
+GET /api/v1/users?fields=id,name,email
+
+# Search
+GET /api/v1/users?q=john
+```
+
+## Best Practices
+
+1. **Use nouns** - Resources are nouns, not verbs
+2. **Use plural names** - `/users` not `/user`
+3. **Use HTTP methods** - Don't put actions in URLs
+4. **Use proper status codes** - Be specific and consistent
+5. **Version your API** - `/api/v1/users`
+6. **Use JSON** - Standard format for requests/responses
+7. **Support pagination** - For collections
+8. **Provide filtering** - Allow clients to filter data
+9. **Use HATEOAS** - Include links in responses (optional)
+10. **Document everything** - Use OpenAPI/Swagger
+11. **Use ISO 8601** - For dates and times
+12. **Use snake_case or camelCase** - Be consistent
+13. **Validate input** - Return 422 for validation errors
+14. **Rate limit** - Protect your API
+15. **Use HTTPS** - Always encrypt traffic
+