Angular Spring Contract

Angular and Spring Boot: the Contract Between Them

This skill owns the seam between an Angular client and a Spring Boot server, and only the seam. Full-stack defects concentrate there because no single-technology skill can see both sides of a wire format at once.

What this skill does not own

1. Establish both halves before giving guidance. The Angular major, the Spring Boot major, the OpenAPI generator and its configuration, and the database types in play. Advice correct for Angular 21 and Boot 4 is wrong on Angular 17 and Boot 3.5.

2. This skill owns only what neither side owns alone. The test: a claim belongs here only if it is false, absent, or misleading when either side is read on its own. Never restate a companion; name it and its file, as in "spring-boot-developer's error-handling.md". If a companion is not installed, say which one is missing and what is therefore unverified, then answer the seam question anyway under a stated assumption. Do not fill the gap by reproducing its content.

3. The OpenAPI document is the source of truth and generated code is never hand-edited. A hand-edit survives until the next generation and then vanishes, usually in someone else's branch. Change the server, regenerate, commit the generated output or generate in CI, but never patch it.

4. Every identifier and every money value crosses the wire as a string. A JSON number is an IEEE 754 double. It silently corrupts any integer above 9 007 199 254 740 991 and cannot represent 0.1. This is not a style preference; the corrupted values are in type-pipeline.md with the exact outputs.

5. A date-only value is not an instant, and an instant is not a local time. LocalDate must not become a JavaScript Date. See dates-and-times.md.

6. The server is the sole authority on authorisation. A route guard is a UX affordance that stops a user seeing a broken page. It protects nothing, and anyone can skip it.

7. After changing anything on the seam, regenerate the client and typecheck both halves. The contract is only proven by a clean compile on both sides, not by either alone.

Every reference carries a ## Version notes section stating what differs across Angular 19 to 21 and Spring Boot 3.5 to 4.x, and a ## Gotchas list of the specific mistakes agents make in that area. Read the gotchas even when skimming. Where a claim is executable it has been executed: the numbers and timezone results in the references are program output, not recollection.

Determining the versions and configuration

Step 1. Server: pom.xml or build.gradle.kts for the spring-boot-starter-parent or plugin version, and the Java release. Client: package.json for @angular/core.

Step 2. Find the contract. Look for a committed openapi.json or openapi.yaml, a springdoc dependency, or an openapi-generator invocation in package.json scripts or the build. If there is no document, say so plainly: without one, the contract is whatever the two sides currently happen to agree on, and every claim below is an assumption.

Step 3. Find the generator and its config. The generated client's shape, its date handling and its enum handling all follow generator options, and those options are where most seam defects are configured in rather than coded in.

Step 4. Identify the database types behind the endpoint. bigint, numeric, timestamptz and uuid each have a wire decision attached, and the column type is where the chain starts.

Adding an Endpoint, End to End, In Order

Topics

• The OpenAPI document and the generated client: what springdoc actually emits, what the generator makes of it, and the three places the generated client contradicts the server that produced it. Read openapi-contract.md
• Type pipeline: Postgres to Java to the wire to TypeScript, for every type where the naive mapping silently loses data: bigint, numeric, uuid, bytea, enums. Read type-pipeline.md
• Dates and times: timestamptz versus date, Instant versus LocalDate, ISO 8601 on the wire, and why a Date in the browser is the wrong type for a date. Read dates-and-times.md
• ProblemDetail: the two error shapes a Spring application actually emits, why the RFC 9457 opt-in does not cover unhandled 500s, and what the Angular interceptor must branch on. Read problem-detail.md
• Pagination: what a Page<T> puts on the wire, why the default envelope publishes Spring Data's internals, and the one property that works on Boot 3.5 and silently does nothing on Boot 4. Read pagination.md
• Auth end to end: where the token lives and what that costs under SSR, the measured refresh stampede and the trap in its usual fix, 401 mid-request, why a guard protects nothing, and what a storageState token does to an e2e suite. Read auth-flow.md
• Optimistic concurrency: ETag and If-Match, why the quotes matter, and what a 412 does and does not tell the client. Read concurrency.md
• File upload: what a rejected upload actually returns, why the limit has to be published, and where the proxy's limit beats yours. Read uploads.md
• Tracing: the traceparent header, why the trace has to start in the browser, and why the id is invisible to the client unless you return it. Read tracing.md
• Checklist: all 40 seam rules in one scannable list, with the five that cause the most damage first. Use this for a review pass. Read checklist.md

Symptom index

Checklist

• Seam checklist: all 40 rules in one list, the five most damaging first, each linked to its reference. Use it for a review pass over an existing pair. Read checklist.md