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---
1.6 KiB
1.6 KiB
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
infrastructuremap 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.