rest-api-architect

Partial of docs/use-cases/UC-001-create-customer/. Owner: rest-api-architect. Inherits the canonical names from 00-caso-de-uso.md and the ports from 10-dominio.md — doesn't reinvent them. Contains no code. Reference shapes in .claude/skills/rest-api-architect/templates/. Rules applied, never reproduced: @.claude/rules/api-rest.md.

Paths below are relative to src/main/java/dev/nerviz/bankapp/infrastructure/rest/. No @RestController exists in the project yet: every class here is NEW.

No GET: the parent spec has no read use case, and an endpoint with no port behind it is a guessed contract. Location still points at the resource's canonical URI; it answers 404 until a read case exists (## Out of scope of the parent spec).

POST /api/v1/customers requires Idempotency-Key: it creates a resource (api-rest.md § Idempotency). The business duplicate guard (unique security number) does not replace it — it answers the second call with 409, where the protocol requires the retried call to get the original 201 back.

Access: public (parent spec). The project has no Spring Security filter chain; the idempotency key's caller identity is the constant anonymous — see block 4.

Every field carries @Schema with description, example and explicit requiredMode = REQUIRED. securityNumber's @Schema documents pattern = "^[0-9]{11}$" for the client; the pattern is not enforced with @Pattern — see block 3.

Why presence only. Every format rule (blank or out-of-range name, 11 digits, date limits) is a domain invariant with its own errorCode (10-dominio.md § 2). A @NotBlank, @Size or @Pattern on the same field would fire first, as a violations 400 without errorCode, and make the domain's code unreachable through this endpoint. Kept to @NotNull, the domain answers each format error with a 400 carrying its errorCode.

Masking — re-derived over the DTO fields by @.claude/rules/logging.md § Masking candidates. Same result as 10-dominio.md § 1, no divergence:

Unreachable through this endpoint, listed so no test asserts them: CUSTOMER_ID_REQUIRED and REGISTERED_AT_REQUIRED (set by the use case, never by the client); CUSTOMER_NAME_REQUIRED, SECURITY_NUMBER_REQUIRED and BIRTH_DATE_REQUIRED for a missing field — intercepted by @NotNull. CUSTOMER_NAME_REQUIRED stays reachable for a blank or whitespace-only name.

Pagination — none: no collection endpoint.

Idempotency — @Idempotent + IdempotencyAspect, first Idempotency-Key endpoint of the project, so every piece is NEW:

Caller identity stored with the key: the constant anonymous — the endpoint is public and the project has no principal to read. When a later case secures the endpoint, the identity becomes the principal's, in that case's impact section.

Schema requirements — read by persistence-architect in its first pass:

Dependencies to add — the executor applies them to pom.xml:

The clock is fixed in the test so "today" is deterministic. Body-shape fixture: templates/error-responses.json.example.

none — the only response body is CustomerResponse { id }, and an aggregate's id is on the counter-list of @.claude/rules/logging.md § Masking candidates. personal-data.md § How to verify grep 1 over the response DTOs designed here: no hit. Security number and birth date enter in the request and never leave in a response or an error detail.

none — no force in the spec, no symptom on disk: one resource, one operation, no @RestController in src/ to repeat. The idempotency aspect is api-rest.md's mandated mechanism, not a pattern chosen here.

none — UC-001 is the first case.