Jon Chery
2c08c778a9
REQ-221: skills/ directory with 9 Atelier-derived skill files mapped to the BA.A citizen-developer catalog: api, security, data, testing, observability, errors, devops, infrastructure-as-code, compliance. Each names the Atelier source path, distills first-principles to the citizen-dev-relevant subset, links to agent-checklist triggers, maps to BA.A 5-skill catalog. REQ-222: docs/skills.md index (9-skill table, Atelier provenance, 8 core principles C1-C8, consumption instructions, reference-only domains, excluded domains). PROJECT.md BA.A decision extended with the Atelier-derived skill catalog reference. ---ci--- project: acdl phase: 4 milestone: v1.18 status: execute requirements: covered: [REQ-221, REQ-222] partial: [] ---/ci---
40 lines
1.6 KiB
Markdown
40 lines
1.6 KiB
Markdown
# Skill: API Design
|
|
|
|
> **Atelier source:** `domains/api/` (first-principles + rest, graphql,
|
|
> versioning, error-responses, pagination)
|
|
> **Core principles:** C1 Correctness, C2 Clarity, C6 Composability
|
|
> **BA.A mapping:** web API skill
|
|
> **Consumer:** read this before authoring an API service contract.
|
|
|
|
## First Principles (citizen-developer-relevant subset)
|
|
|
|
- **Endpoints are nouns, plural, lowercase-hyphenated.** (`/customers`,
|
|
not `/getCustomer`)
|
|
- **Status codes are correct.** 200/201/204/4xx/5xx per semantics.
|
|
- **Errors are structured.** Every error response carries `code`,
|
|
`message`, `request_id` — not a stack trace.
|
|
- **Input is validated against a schema.** The contract's
|
|
`infrastructure` map is validated at resolution time; the API must
|
|
validate its own request bodies.
|
|
- **Auth is required by default.** No unauthenticated endpoints unless
|
|
explicitly declared in `policyPreconditions`.
|
|
|
|
## Agent-Checklist Triggers
|
|
|
|
Before completing an API task, run these (from
|
|
`review/agent-checklist.md` § API):
|
|
|
|
- Endpoints are nouns, plural, lowercase-hyphenated
|
|
- Status codes are correct per semantics
|
|
- Errors are structured (code, message, request_id)
|
|
- Input is validated against a schema
|
|
- Auth is required by default
|
|
|
|
## How Nova Uses This
|
|
|
|
The submission-readiness gate (`schemas/submission-readiness.schema.json`)
|
|
checks that your contract declares `policyPreconditions`. The API skill
|
|
tells you what the platform expects your application to enforce on its
|
|
own surface (request validation, structured errors, auth). Nova does
|
|
not author your API; it deploys it. The API skill ensures the
|
|
application you deploy meets production-grade standards. |