Accepted5 Nov 2026
0034. Keep the FastAPI API's HTTP contract in Spring MVC
Context and Problem Statement#
Stage 2 replaced the FastAPI API with archsim-app while the web app, the CLI, scripts and the
black-box suite kept calling it (ADR-0019).
Spring MVC answers differently by default: /error bodies with timestamp, status and path
for a missing route or method, a different 413, no security headers, controllers at the root.
How much of FastAPI's behaviour should the Java API reproduce, and where does that code live?
Decision Drivers#
- Clients keep working: what a client read from the Python API it reads from the Java one.
- One place for each cross-cutting rule, not repeated in every controller.
- Features don't know about the contract's framing: a service throws, the web layer answers.
Considered Options#
- Reproduce the contract in the
webpackage: an exception handler, two servlet filters and a path prefix - Spring's defaults, and change the clients
- RFC 9457 problem details (
application/problem+json), and change the clients
Decision Outcome#
Chosen option: "reproduce the contract in the web package", because clients kept working
unchanged and each rule is written once.
- Error bodies. A refusal is
{"detail": {"message": "...", "issues": [...]}},issuesbeing the design's validation issues as the model writes them (ErrorBody). A feature throwsApiExceptionwith a status, message and issues;ApiExceptionHandlerwrites the body. - What Spring refuses on its own keeps Spring's status and headers and gets Starlette's body:
a route that does not exist is
404 {"detail": "Not Found"}, a method a route does not take is405 {"detail": "Method Not Allowed"}withAllow: GET, HEAD, and so on (ApiExceptionHandlerextendsResponseEntityExceptionHandler). A failure is a logged500with Starlette's plain-textInternal Server Error. Errors the servlet container handles reachApiErrorController, which answers them the same way, and/erroritself is a route that does not exist. Tomcat decodes%2Fin a path, as Starlette does; since ADR-0065, Spring Security's request firewall is set to let%2Fand a path parameter (;) through, and refuses the rest of what it refuses with400(archsim-app's README lists it). - Request bodies. An endpoint reads its body as a record with the model's codec (
@ApiBody), which reports what does not fit as pydantic does; the answer is FastAPI's422 {"detail": [{"type", "loc", "msg", "input"}]}, which the web app shows. - Content. Answers are JSON whatever the request's
Acceptsays, as FastAPI's are. - CORS with Starlette's settings (any method and header, preflight cached 600 s) and its leniency: a request from an origin that is not listed is served without CORS headers rather than refused, because requests the web server passes on carry the site's origin.
- Security headers on every response (
SecurityHeadersFilter; since ADR-0065, Spring Security'sheaders()asSecurityHeaderssets them):nosniff,DENYframing,no-referrer, same-origin resource policy, a permissions policy, a content-security policy except on the interactive docs,no-storeon the private routes (auth,tokens,workspaces,invitations) and HSTS whenARCHSIM_PUBLIC_URLishttps. - Body size (
BodySizeFilter), before anything reads the body:413overARCHSIM_MAX_BODY_BYTES,411for a chunked body onPOST,PUTorPATCH, with the error body. - Paths. Every controller of
io.archsim.appis served under/api/v1(WebConfiguration); the OpenAPI document and interactive docs are at/api/v1/openapi.jsonand/api/v1/docs. - JSON field names are the Python API's camelCase; dates, numbers and
nulls are written as it writes them, endpoint by endpoint, and the black-box suite checks them. Numbers are compared by value, as the golden files compare them: where Python writes a whole number as600and Java as600.0, or the other way round, clients read the same number.
Where the Python API had a bug, the Java API does not copy it. It also differed from FastAPI in
24 accepted ways.
archsim-app's README lists both.
Among the differences: a trailing slash was 404 where Starlette redirected (307);
a body that didn't fit was 422 before access was checked, where FastAPI answered 404 or 403
first; numbers came back spelled as Java writes them (5.0E-4 for 0.0005). The web app, the
black-box suite and the Playwright tests passed with them.
Since 12 Nov 2026: a request body ignores the keys it does not know, as FastAPI's request
models did (their ApiModel set no extra, so pydantic ignored them). The Java API had refused
them with extra_forbidden, a break of this contract nobody chose, found in stage 6 of the port
and closed: each request record is marked @IgnoreUnknownKeys, a test holds every @ApiBody
record to it, and the black-box suite's UnknownKeysTests checks it over HTTP. A design document
in a body keeps its own models' rule and refuses its unknown keys, as the engine's did.
Consequences#
- Good, because the web app, CLI and black-box suite ran against either API unchanged, apart from the accepted differences.
- Good, because a feature only throws
ApiException; its controller has no error handling. - Bad, because Spring's own error page and problem-details support go unused, and a new kind of
framework exception needs a mapping in
ApiExceptionHandlerto keep the contract.
Confirmation#
WebBehaviourTests check the 404, 405, 411, 413 and 422 bodies, the headers, Accept and CORS;
ServedApplicationTests check the container's answers on a real Tomcat; the controller tests check
each body; the black-box suite runs against the Java API in CI, as it ran against the Python
one until stage 2 (ADR-0019).
Pros and Cons of the Options#
Spring's defaults, and change the clients#
- Good, because there is no contract code.
- Bad, because the web app and every script would change in the same release as the API, which stage 2 must avoid.
RFC 9457 problem details#
- Good, because it is a standard Spring supports.
- Bad, because it changes every error body clients read; it can be adopted in
/api/v2.