@polymorphism-tech/morph-spec 4.3.4 → 4.3.5

package/.morph/standards/backend/api/rest.md

@@ -0,0 +1,492 @@
+# REST API Standards
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** rest, api, endpoint, controller, http, restful
+> **Load When:** always
+
+RESTful API design conventions and best practices
+
+---
+
+## HTTP Methods
+
+| Method | Usage | Idempotent | Safe |
+|--------|-------|------------|------|
+| GET | Retrieve resource(s) | ✅ Yes | ✅ Yes |
+| POST | Create new resource | ❌ No | ❌ No |
+| PUT | Replace entire resource | ✅ Yes | ❌ No |
+| PATCH | Partial update | ❌ No | ❌ No |
+| DELETE | Remove resource | ✅ Yes | ❌ No |
+
+---
+
+## URL Conventions
+
+### Resource Naming
+
+```
+✅ GOOD
+/api/users
+/api/users/123
+/api/users/123/orders
+/api/orders/456/items
+
+❌ BAD
+/api/getUsers
+/api/user
+/api/User
+/api/users/getAllOrders
+```
+
+### Rules
+
+- Use **plural nouns** for collections (`/users`, not `/user`)
+- Use **lowercase** (`/users`, not `/Users`)
+- Use **hyphens** for multi-word resources (`/order-items`, not `/orderItems`)
+- Use **forward slashes** for hierarchy (`/users/123/orders`)
+- **No trailing slash** (`/users`, not `/users/`)
+- **No verbs** in URLs (`/users`, not `/getUsers`)
+
+---
+
+## Endpoint Patterns
+
+### Collection Operations
+
+```http
+GET    /api/users              # List all users
+POST   /api/users              # Create new user
+GET    /api/users/123          # Get user by ID
+PUT    /api/users/123          # Replace user
+PATCH  /api/users/123          # Update user
+DELETE /api/users/123          # Delete user
+```
+
+### Nested Resources
+
+```http
+GET    /api/users/123/orders           # Get user's orders
+POST   /api/users/123/orders           # Create order for user
+GET    /api/users/123/orders/456       # Get specific order
+DELETE /api/users/123/orders/456       # Delete user's order
+```
+
+### Actions (Non-CRUD)
+
+```http
+POST   /api/users/123/activate         # Activate user
+POST   /api/orders/456/cancel          # Cancel order
+POST   /api/orders/456/refund          # Refund order
+```
+
+---
+
+## HTTP Status Codes
+
+### Success (2xx)
+
+| Code | Meaning | Usage |
+|------|---------|-------|
+| 200 OK | Success | GET, PUT, PATCH (with body) |
+| 201 Created | Resource created | POST |
+| 204 No Content | Success, no body | DELETE, PUT, PATCH (no body) |
+
+### Client Error (4xx)
+
+| Code | Meaning | Usage |
+|------|---------|-------|
+| 400 Bad Request | Invalid input | Validation errors |
+| 401 Unauthorized | Not authenticated | Missing/invalid token |
+| 403 Forbidden | Not authorized | Insufficient permissions |
+| 404 Not Found | Resource not found | Invalid ID |
+| 409 Conflict | Conflict | Duplicate email, version conflict |
+| 422 Unprocessable Entity | Validation failed | Business rule violation |
+
+### Server Error (5xx)
+
+| Code | Meaning | Usage |
+|------|---------|-------|
+| 500 Internal Server Error | Unexpected error | Unhandled exceptions |
+| 503 Service Unavailable | Service down | Maintenance, overload |
+
+---
+
+## Request/Response Examples
+
+### GET (List)
+
+**Request:**
+
+```http
+GET /api/users?page=1&limit=20&sort=email&filter=active
+```
+
+**Response:**
+
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "email": "user@example.com",
+      "name": "John Doe",
+      "createdAt": "2026-02-16T10:00:00Z"
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 45,
+    "totalPages": 3
+  }
+}
+```
+
+### GET (Single)
+
+**Request:**
+
+```http
+GET /api/users/123
+```
+
+**Response:**
+
+```json
+{
+  "id": 123,
+  "email": "user@example.com",
+  "name": "John Doe",
+  "createdAt": "2026-02-16T10:00:00Z"
+}
+```
+
+### POST (Create)
+
+**Request:**
+
+```http
+POST /api/users
+Content-Type: application/json
+
+{
+  "email": "newuser@example.com",
+  "name": "Jane Smith",
+  "password": "SecurePass123!"
+}
+```
+
+**Response:**
+
+```http
+HTTP/1.1 201 Created
+Location: /api/users/124
+
+{
+  "id": 124,
+  "email": "newuser@example.com",
+  "name": "Jane Smith",
+  "createdAt": "2026-02-16T11:00:00Z"
+}
+```
+
+### PUT (Replace)
+
+**Request:**
+
+```http
+PUT /api/users/123
+Content-Type: application/json
+
+{
+  "email": "updated@example.com",
+  "name": "John Updated"
+}
+```
+
+**Response:**
+
+```http
+HTTP/1.1 200 OK
+
+{
+  "id": 123,
+  "email": "updated@example.com",
+  "name": "John Updated",
+  "updatedAt": "2026-02-16T11:30:00Z"
+}
+```
+
+### DELETE
+
+**Request:**
+
+```http
+DELETE /api/users/123
+```
+
+**Response:**
+
+```http
+HTTP/1.1 204 No Content
+```
+
+---
+
+## Error Responses
+
+### Standard Error Format
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed for one or more fields",
+    "details": [
+      {
+        "field": "email",
+        "message": "Email is required"
+      },
+      {
+        "field": "password",
+        "message": "Password must be at least 8 characters"
+      }
+    ]
+  }
+}
+```
+
+### Error Codes
+
+```json
+// 400 Bad Request
+{
+  "error": {
+    "code": "INVALID_INPUT",
+    "message": "Invalid request body"
+  }
+}
+
+// 401 Unauthorized
+{
+  "error": {
+    "code": "UNAUTHORIZED",
+    "message": "Authentication required"
+  }
+}
+
+// 403 Forbidden
+{
+  "error": {
+    "code": "FORBIDDEN",
+    "message": "Insufficient permissions to access this resource"
+  }
+}
+
+// 404 Not Found
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "User with ID 123 not found"
+  }
+}
+
+// 409 Conflict
+{
+  "error": {
+    "code": "CONFLICT",
+    "message": "Email already exists"
+  }
+}
+
+// 500 Internal Server Error
+{
+  "error": {
+    "code": "INTERNAL_ERROR",
+    "message": "An unexpected error occurred"
+  }
+}
+```
+
+---
+
+## Pagination
+
+### Query Parameters
+
+```http
+GET /api/users?page=2&limit=20
+```
+
+### Response Format
+
+```json
+{
+  "data": [...],
+  "meta": {
+    "page": 2,
+    "limit": 20,
+    "total": 150,
+    "totalPages": 8
+  },
+  "links": {
+    "first": "/api/users?page=1&limit=20",
+    "prev": "/api/users?page=1&limit=20",
+    "self": "/api/users?page=2&limit=20",
+    "next": "/api/users?page=3&limit=20",
+    "last": "/api/users?page=8&limit=20"
+  }
+}
+```
+
+---
+
+## Filtering and Sorting
+
+### Query Parameters
+
+```http
+# Filter by status
+GET /api/orders?status=pending
+
+# Filter by date range
+GET /api/orders?startDate=2026-01-01&endDate=2026-02-01
+
+# Sort ascending
+GET /api/users?sort=email
+
+# Sort descending
+GET /api/users?sort=-createdAt
+
+# Multiple filters
+GET /api/orders?status=pending&customer=123&sort=-createdAt
+```
+
+---
+
+## Versioning
+
+### URL Versioning (Recommended)
+
+```http
+GET /api/v1/users
+GET /api/v2/users
+```
+
+### Header Versioning
+
+```http
+GET /api/users
+Accept: application/vnd.api.v1+json
+```
+
+---
+
+## Best Practices
+
+### DO
+
+✅ **Use plural nouns**
+
+```http
+✅ GET /api/users
+❌ GET /api/user
+```
+
+✅ **Return appropriate status codes**
+
+```csharp
+// ✅ CORRECT
+[HttpPost]
+public async Task<IActionResult> CreateUser(CreateUserRequest request)
+{
+    var user = await _userService.CreateAsync(request);
+    return CreatedAtAction(nameof(GetUser), new { id = user.Id }, user);
+}
+```
+
+✅ **Use DTOs (not entities)**
+
+```csharp
+// ✅ CORRECT
+public record UserResponse(int Id, string Email, string Name);
+
+[HttpGet("{id}")]
+public async Task<ActionResult<UserResponse>> GetUser(int id)
+{
+    var user = await _userService.GetByIdAsync(id);
+    return Ok(new UserResponse(user.Id, user.Email, user.Name));
+}
+```
+
+✅ **Validate input**
+
+```csharp
+public record CreateUserRequest
+{
+    [Required]
+    [EmailAddress]
+    public string Email { get; init; }
+
+    [Required]
+    [MinLength(8)]
+    public string Password { get; init; }
+}
+```
+
+### DON'T
+
+❌ **Don't use verbs in URLs**
+
+```http
+❌ POST /api/createUser
+✅ POST /api/users
+```
+
+❌ **Don't expose internal IDs**
+
+```csharp
+// ❌ WRONG (exposes database ID)
+public class User
+{
+    public int Id { get; set; } // Internal DB ID
+}
+
+// ✅ CORRECT (use public UUID)
+public class UserResponse
+{
+    public Guid PublicId { get; init; }
+}
+```
+
+❌ **Don't return entities directly**
+
+```csharp
+// ❌ WRONG
+[HttpGet]
+public async Task<List<User>> GetUsers()
+{
+    return await _context.Users.ToListAsync(); // Exposes all properties!
+}
+
+// ✅ CORRECT
+[HttpGet]
+public async Task<List<UserResponse>> GetUsers()
+{
+    var users = await _context.Users.ToListAsync();
+    return users.Select(u => new UserResponse(u.Id, u.Email, u.Name)).ToList();
+}
+```
+
+---
+
+## Related Standards
+
+- [Error Handling](./error-handling.md)
+- [Validation](./validation.md)
+- [Minimal API](./ minimal-api.md)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/standards/backend/api/validation.md

@@ -0,0 +1,88 @@
+# Status Validation Pattern
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** validation, fluent, dto, modelstate, fluentvalidation
+> **Load When:** always
+
+**MORPH-SPEC Standard** — Validate what is INVALID, not what is valid.
+
+## Problem
+
+Validations assuming a single flow break when new flows are added.
+
+```
+Original: Created → PendingPayment → Processing → Completed → EmailSent
+Free:     Created → Processing → Completed → EmailSent  (skips payment)
+```
+
+```csharp
+// ❌ Assumes single flow — breaks free flow
+if (order.Status != OrderStatus.PendingPayment)
+    throw new InvalidOperationException("Must be pending payment");
+
+// ✅ Validates invalid states — works for all flows
+if (order.Status >= OrderStatus.Completed || order.Status == OrderStatus.Failed)
+    throw new InvalidOperationException("Order already completed or failed");
+```
+
+## Enum Design
+
+```csharp
+public enum OrderStatus
+{
+    Created = 0, PendingPayment = 1, Processing = 2, Completed = 3, EmailSent = 4,
+    // Error states (separated range)
+    Failed = 100, Cancelled = 101, Refunded = 102
+}
+```
+
+## Validation Patterns
+
+| Pattern | When | Example |
+|---------|------|---------|
+| Final state check | Block after completion | `if (status >= OrderStatus.Completed)` |
+| Error state list | Block specific errors | `if (new[] { Failed, Cancelled, Refunded }.Contains(status))` |
+| Range comparison | Block finalized + errors | `if (status >= Completed \|\| status >= Failed)` |
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| `if (status != Expected)` | Assumes single flow | Validate invalid states instead |
+| Exhaustive switch on valid states | Must modify for each new status | Validate only invalid states |
+| Business logic in state validator | Mixed concerns | Separate state validation from business rules |
+
+## Complete Example
+
+```csharp
+public async Task<Result> ProcessOrderAsync(Guid orderId, CancellationToken ct)
+{
+    var order = await _repository.GetByIdAsync(orderId, ct);
+    if (order == null) return Result.Failure("Order not found");
+
+    // State validation (invalid states)
+    if (order.Status >= OrderStatus.Completed) return Result.Failure("Already completed");
+    if (order.Status == OrderStatus.Failed) return Result.Failure("Cannot process failed order");
+    if (order.Status == OrderStatus.Cancelled) return Result.Failure("Cannot process cancelled order");
+
+    // Business validation (separate)
+    if (order.RequiresPayment && !order.IsPaid) return Result.Failure("Payment required");
+
+    order.MarkAsProcessing();
+    await _repository.UpdateAsync(order, ct);
+    return Result.Success();
+}
+```
+
+## Checklist
+
+- [ ] Validates INVALID states (not valid)?
+- [ ] Uses ordered enum comparison where possible?
+- [ ] Error states treated separately (100+ range)?
+- [ ] All flows documented in decisions.md?
+- [ ] Tested with all possible flows?
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*