# 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.