jsdlc-api-spec

# API Specification (API仕様書) Request / arguments: $ARGUMENTS Mode is the first word: `create` (default), `review`, `modify`. Read before acting: - `docs-jsdlc/templates/api-spec.md` - `docs-jsdlc/rules/id-and-traceability.md` - `docs-jsdlc/rules/review-checklist.md` §2 and §5 - `docs-jsdlc/rules/diagram-rules.md`, when profile §7 says PlantUML is used The API spec is a **contract**. Its readers include people who cannot read the implementation — a frontend team, another vendor, the client's own reviewers. Anything ambiguous here becomes an integration defect later. --- ## Mode: create ### Step 1 — Establish the input Find the detail design items this API group exposes. Every operation must name a `DD-<DOM>-<nnn>` in its `Design ref`. An operation with no detail design parent is not specifiable — stop and say so. If the controller code exists, read it and reconcile. Where code and design disagree, the design wins and the difference becomes a finding to report. When the project profile §8 names a parameter sheet, it is an input here too — field names, lengths and code values in the spec must match it, and a mismatch is a `Q-NNN` naming the sheet and the row. ### Step 2 — Write the common section first §1 is written once and binds every operation: - envelope shape, identical for success and failure across all operations - common headers, with the behaviour when a required one is missing - date-time format with a literal example - the common error code table, taken from the basic design message list An operation that deviates from the common envelope is a design defect, not a special case. If a deviation is genuinely required, raise `Q-NNN`. ### Step 3 — Write each operation Per operation, every field in every table. Quality bars: - **Types and constraints** — type, format, required, constraint, example, for request and response alike. "String" alone is insufficient; give the length. - **Every failure status** — enumerate them. A status the implementation can return but the spec omits is the most common integration defect. - **Error codes map 1:1 to the basic design message list.** Never invent. - **Samples must validate against the field table.** Write the table first, then derive the sample from it — not the reverse. A sample containing a field absent from the table is NG. - **Idempotency** — state it per operation. If undetermined, `Q-NNN`. - **Side effects** — events published, files written, downstream calls. A silent side effect is a contract violation. - **Diagram, only when the flow needs one.** When profile §7 says PlantUML is used, draw a sequence diagram per `docs-jsdlc/rules/diagram-rules.md` for operations where three or more parties exchange messages, or where there is a callback, a redirect or a polling loop. A plain request → response operation gets no diagram — the field tables already say everything, and an extra diagram is one more thing to go stale. ### Step 4 — Self-check and save Run §5 checks. Verify each sample against its own table field by field. Save to `docs-jsdlc/output/api-spec/API-<DOM>-<group>.md`. ### Step 5 — Report Operations specified, failure statuses documented, error codes used (and confirmation each exists upstream), questions raised. --- ## Mode: review Do not edit. Run §2 and §5 checks individually with evidence. The checks that repay the most attention: - **A-03 envelope consistency** — compare every operation's response shape against §1.4 literally, field by field. - **A-04 error code provenance** — resolve every code against the basic design message list. An unresolvable code is NG. - **A-07 sample validity** — parse each sample against its field table. Missing required fields, extra fields, and wrong types are all NG. - **A-01 status completeness** — if the implementation exists, list every status it can return and confirm the spec covers each. Write to `docs-jsdlc/output/review/API-<DOM>-<group>-review-<YYYYMMDD>.md`. --- ## Mode: modify 1. Fix every NG, each traceable to a finding number. Every NG you close carries the follow-through its class requires — see `docs-jsdlc/rules/review-checklist.md` §9. Closing the symptom without the follow-through leaves the defect class open, and the next review will find it again. A deferral counts as closed only with a `Q-NNN`, a named decider, and a due phase. 2. Promote 要確認 to `Q-NNN`. 3. **Compatibility analysis is mandatory.** For every change, classify it: - **Breaking** — removed field, narrowed type, new required field, changed status code, changed error code. - **Non-breaking** — new optional field, new operation, documentation only. Report every breaking change explicitly with the consumers it affects. Per the project's architecture document, contract changes require a consumer compatibility check; you cannot perform it, so you must surface it. 4. Bump the revision history. 5. Report fixes, promoted questions, and the breaking-change list.