apiVersion: devrunbook.io/v1alpha1 kind: Playbook metadata: id: feature-implementation.api-endpoint slug: api-endpoint version: 1.0.0 title: Add a Compatible API Endpoint summary: Implement a new endpoint with validated input, authorization, stable errors, documentation and contract tests. category: feature-implementation tags: - api - endpoint - contracts lifecycle: reviewed riskTier: moderate authors: - name: DevRunbook Core Team license: MIT package: files: - path: prompt.md role: template digest: true exportByDefault: false - path: README.md role: documentation digest: true exportByDefault: false - path: CHANGELOG.md role: changelog digest: true exportByDefault: false - path: examples/minimal.yaml role: example digest: true exportByDefault: false - path: evaluations/static-structure.yaml role: evaluation digest: true exportByDefault: false spec: type: guided intent: problem: Development work around add a compatible api endpoint is often underspecified, inconsistently executed or reported without enough evidence. outcome: Implement a new endpoint with validated input, authorization, stable errors, documentation and contract tests. whenToUse: - Use this playbook when the repository needs a bounded add a compatible api endpoint task with explicit evidence and completion criteria. - Use it when Codex should follow a repeatable workflow rather than improvise from a one-line request. whenNotToUse: - Do not use it when the desired outcome or authority boundaries are still materially undecided. - Do not use it to access unavailable production credentials, bypass safeguards or claim validation that cannot be performed. modes: - guided - execute - recovery defaultMode: execute autonomy: min: implement max: repair default: verify inputs: - key: endpointBehavior label: Endpoint behavior description: Describe method, route intent, request, response, errors and compatibility expectations. type: multiline required: true sensitive: false includeInOutput: true - key: authorization label: Authorization description: Describe who may call the endpoint and how ownership or workspace boundaries apply. type: multiline required: true sensitive: false includeInOutput: true compatibility: repositoryRequired: true languages: [] frameworks: [] packageManagers: [] databases: [] deploymentTypes: [] requiredProfileCapabilities: [] incompatibleConditions: [] guardrails: - id: guardrail-1 severity: blocking text: Preserve existing API conventions, error shapes and compatibility unless the specification explicitly changes them. - id: guardrail-2 severity: blocking text: Enforce authentication, authorization, ownership and validation server-side. - id: guardrail-3 severity: blocking text: Do not expose internal errors, secrets or unrestricted database objects in responses. workflow: - id: inspect-contracts title: Inspect existing contracts instruction: Review routing, validation, service boundaries, authorization and OpenAPI patterns. required: true - id: design-contract title: Design endpoint contract instruction: Specify method, route, request, response, errors, idempotency, pagination and compatibility. required: true - id: implement-domain title: Implement behavior instruction: Add domain/application logic before thin transport wiring and keep ownership checks explicit. required: true - id: implement-transport title: Implement endpoint instruction: Add schema validation, response mapping, error translation and audit behavior. required: true - id: test-contract title: Test contract instruction: Add unit, integration, authorization and negative tests. required: true - id: update-docs title: Update API documentation instruction: Keep generated and source OpenAPI synchronized with examples. required: true - id: verify title: Run validation instruction: Run relevant lint, typecheck, tests, build and targeted API smoke checks. required: true validation: commandRoles: - lint - typecheck - unit-test - integration-test - build checks: - id: check-1 type: assertion description: The endpoint contract and implementation remain synchronized. blocking: true evidence: Referenced files, command results or explicit review notes. - id: check-2 type: assertion description: Authorization and negative validation tests prove boundary behavior. blocking: true evidence: Referenced files, command results or explicit review notes. - id: command-lint type: command description: Run the resolved lint command when the repository profile provides it and record the result. blocking: true evidence: Resolved command, exit status and concise result summary. - id: command-typecheck type: command description: Run the resolved typecheck command when the repository profile provides it and record the result. blocking: true evidence: Resolved command, exit status and concise result summary. - id: command-unit-test type: command description: Run the resolved unit-test command when the repository profile provides it and record the result. blocking: true evidence: Resolved command, exit status and concise result summary. - id: command-integration-test type: command description: Run the resolved integration-test command when the repository profile provides it and record the result. blocking: true evidence: Resolved command, exit status and concise result summary. - id: command-build type: command description: Run the resolved build command when the repository profile provides it and record the result. blocking: true evidence: Resolved command, exit status and concise result summary. completion: criteria: - Endpoint contract is documented and tested. - Existing clients and routes remain compatible. - Validation evidence and unresolved limitations are reported honestly. failurePolicy: onValidationFailure: Investigate failures caused by the current work, repair them when they remain within scope, rerun affected validation and report any genuine blocker without claiming success. onAmbiguity: Use repository evidence and existing conventions for minor reversible choices. Preserve current behavior and stop before any material irreversible decision that the specification does not resolve. onMissingContext: Inspect the repository for missing non-sensitive context. Never invent commands, credentials, production behavior or validation results; report what remains unavailable. onOutOfScopeCause: Explain the evidenced out-of-scope cause, avoid unrelated changes and provide the smallest safe follow-up recommendation. onExternalDependencyUnavailable: Use an approved local substitute or fixture only when it preserves the behavior under test. Otherwise record the blocked validation and do not claim the external path succeeded. onUnableToReproduce: Record attempted reproduction, environment and observed evidence. Do not apply speculative production changes; provide the narrowest next diagnostic action. reporting: sections: - id: outcome title: Outcome required: true description: State the delivered result or audit conclusion without overstating evidence. - id: evidence title: Evidence and scope required: true description: List inspected or changed areas and the evidence supporting the result. - id: validation title: Validation required: true description: Report commands, manual checks and their actual outcomes. - id: risks title: Risks and limitations required: true description: State residual risk, inaccessible evidence and untested conditions. - id: follow-up title: Recommended follow-up required: true description: List the smallest useful next actions or state None. template: main: prompt.md partials: [] exports: prompt: true markdown: true runPack: false agentsSuggestion: false quality: reviewStatus: editorial-reviewed testedStacks: [] knownLimitations: - Repository-specific effectiveness depends on the accuracy of the selected profile and the evidence available to Codex. evaluationCaseIds: - api-endpoint.static-structure