Software Development Models Explained

Parameters The Waterfall pipeline depends on API-reference quality and developer-guide precision. For an HTTP API contract, document these parameters:

| Parameter | Type | Required | Description | |---|---|---|---| | method | string | yes | HTTP method (e.g., GET, POST) | | path | string | yes | URL path template (e.g., /v1/courses/{courseId}) | | baseUrl | string | yes | Environment base URL (e.g., https://api.example.com) | | pathParams | object | optional | Map of {name: type} (e.g., courseId: string) | | queryParams | object | optional | Map of {name: {type, default}} (e.g., limit: {type:int, default:20}) | | requestBodySchema | object | conditional | JSON schema for POST/PUT/PATCH | | responseSchema | object | yes | JSON schema for successful responses | | statusCodes | object | yes | Map of HTTP status to schema (e.g., 200, 400, 404) | | auth | object | conditional | Auth mode (e.g., bearerToken) and header name | | rateLimit | object | optional | Quota policy (e.g., requestsPerMinute) | | errorFormat | object | yes | Standard error payload fields (e.g., code, message, details) |

Code Example Below is a minimal Node.js/Express route that matches a documented Waterfall API contract (including structured errors). In Waterfall, this code is produced only after the API contract and response schemas are approved at Gate 1 and Gate 2.

`js // app.js import express from "express";

const app = express(); app.use(express.json());

// Example: POST /v1/courses // Contract (Gate 1/2): // - 201 on success with responseSchema { id: string, name: string } // - 400 on validation with errorFormat { code, message, details } app.post("/v1/courses", async (req, res) => { const { name } = req.body?? {};

// Gate 4 testing will cover: missing name, non-string name, and success path. if (typeof name!== "string" || name.trim().length < 1) { return res.status(400).json({ code: "VALIDATION_ERROR", message: "Field 'name' is required and must be a non-empty string.", details: [{ field: "name", issue: "missing_or_empty" }], }); }

// In Waterfall, persistence/migrations are aligned in Gate 2 design. const id = crypto.randomUUID();

return res.status(201).json({ id, name: name.trim(), }); });

export default app; `

Response Format Document the expected JSON response structures as part of the developer guide and API reference.

json { "success": true, "data": { "id": "string", "name": "string" }, "meta": { "requestId": "string" } }

Error response format (400/404/500): json { "success": false, "error": { "code": "string", "message": "string", "details": [ { "field": "string", "issue": "string" } ] }, "meta": { "requestId": "string" } }

Field notes: - requestId enables traceability across logs during Gate 5 deployment. - details is an array to keep validation errors stable across versions.

Notes & Best Practices - Lock the API contract at Gate 1: endpoints, schemas, and status codes must not change during Gate 3 coding without a documented re-gate (requirements + design). - Error handling must be schema-driven: keep code/message/details stable so Gate 4 tests remain valid. - Test timing is strict: Gate 4 executes tests after code freeze; avoid “late” test additions that imply contract drift. - Deployment manifest is part of Gate 5: include version, environment variables, and rollback command reference to prevent mismatched behavior after release.

Waterfall’s strict pipeline makes documentation and contracts central to delivery; the next chapter compares this with iterative models where contract changes are handled through repeated planning and evaluation cycles.

End of chapter one. 4 more chapters in the full book.