docs(P05): complete examples phase

examples/good/api-endpoint.md

@@ -0,0 +1,79 @@
+# Good Example: API Endpoint
+
+> A REST endpoint that follows Atelier's API principles. Each aspect cites the principle it satisfies.
+
+## The Endpoint
+
+```typescript
+// POST /v1/orders — create an order
+router.post('/v1/orders', auth, validate(CreateOrderSchema), async (req, res) => {
+  const { userId, items } = req.body;
+
+  const order = await orderService.create({ userId, items });
+
+  res.status(201).location(`/v1/orders/${order.id}`).json({
+    data: order,
+  });
+});
+```
+
+## What Makes It Good
+
+### Resource Naming (API P2 Clarity, P3 Predictability)
+- `/v1/orders` — noun, plural, lowercase, hyphenated.
+- Versioned (`/v1`) — P5 Versioning.
+- No verb in the URL; the HTTP method is the verb.
+
+### Method Semantics (API P1 Contract Fidelity, P6 Idempotency)
+- POST for creation. 201 on success (not 200). `Location` header for the new resource.
+- Idempotency key supported via middleware (omitted for brevity) — P6.
+
+### Authentication (API P8 Security, Security P1 Zero Trust)
+- `auth` middleware runs on every endpoint by default. No opt-in auth.
+- The endpoint does not re-implement auth; it relies on the boundary check.
+
+### Input Validation (API P8, Security P4 Input Validation)
+- `validate(CreateOrderSchema)` — schema-based validation at the boundary.
+- The schema (zod, joi, etc.) defines types, ranges, required fields.
+- Unknown fields rejected (`additionalProperties: false` in the schema).
+
+### Response Shape (API P2 Clarity)
+- `{ data: order }` — wrapped, not a bare object. Allows adding pagination/metadata without breaking.
+- The shape is consistent across all endpoints in the API.
+
+### Error Handling (API P9 Error Transparency, Errors P1 Errors are Data)
+- Errors thrown in `orderService.create` are caught by centralized middleware.
+- Errors are structured: `{ error: { code, message, request_id } }`.
+- 404 → `ORDER_NOT_FOUND`, 409 → `DUPLICATE_ORDER`, 422 → `VALIDATION_FAILED`.
+
+### Observability (Observability P2 Correlation, P3 Sufficient Context)
+- `request_id` propagated via middleware. Every log in the request includes it.
+- Significant events logged: "order created", "order creation failed".
+
+### Economy (Core C8, Performance P4 Resource Bounds)
+- The order creation is bounded in time (the service has a timeout).
+- No unbounded query; no loading all products into memory.
+
+## The Schema (for completeness)
+
+```typescript
+const CreateOrderSchema = z.object({
+  userId: z.string().uuid(),
+  items: z.array(z.object({
+    productId: z.string().uuid(),
+    quantity: z.number().int().positive().max(100),
+  })).min(1).max(50),
+}).strict();  // additionalProperties: false
+```
+
+- `userId` is a UUID (Data P7 Type Fidelity).
+- `quantity` is bounded (Performance P4).
+- `items` is bounded (1–50) (Performance P4, Security P10 Surface Minimization).
+- `.strict()` rejects unknown fields (Security P4).
+
+## What This Example Does NOT Do (And Why That's Good)
+
+- Does not return 200 on error — the status code is the first signal (API P9).
+- Does not log the request body — may contain PII (Observability P6, Security P9).
+- Does not construct SQL by string interpolation — uses a service layer (Security P5 Output Safety).
+- Does not skip auth for "internal" callers — Zero Trust (Security P1).