The Mock That Never Says 404
A payments team owns an Order API specified in RAML 1.0 inside Design Center and published to Exchange. GET /orders/{orderId} declares a 200 response with an Order example and a 404 response with an Error type, but the 404 has no example attached. The public mocking service returns the 200 example for every orderId, including orderId=abc. Two consumer teams are now building against that mock and have assumed the API never returns errors. A third team wants to reuse the Error type and the X-Correlation-Id and X-Total-Count headers across four other APIs. Separately, the implementation team wants to change orderId from string to integer and rename the parameter to id.
1. The consumer teams say the mock is "lying." Explain what the mocking service does and does not do, and what spec changes would make it useful for error-path testing.
Read the worked answer
What the mock is: a spec-driven stub. It is generated from the RAML and returns the response bodies declared in it. It does not run business logic, inspect path values, or decide that abc is invalid.
Why consumers see 200 for everything: the only example present is on the 200 response, so that is the only one the mock can serve. The 404 exists as a media type but has no concrete representation.
Fixes, in order of value:
- Add an explicit
examplesblock on the 404 response (and on a new 400 for a malformed identifier) so the error shape is visible and copy-pasteable. - Document the error codes in the type/description so a consumer knows which 4xx/5xx to expect.
- Accept that per-identifier behaviour cannot be tested against a mock. Error-path testing belongs against a real implementation in a sandbox, or against an API proxy in a test environment where faults can be injected.
The judgement point: do not weaken the contract to match the mock, and do not promise consumers that the mock is a test harness.
2. Evaluate the proposed change from `string` to `integer` and from `orderId` to `id`. Should it be made on the current spec?
Read the worked answer
Both edits are breaking contract changes, not cosmetic ones.
- Type change alters generated client signatures and any consumer-side validation; a string-typed path parameter accepting
"A-1001"stops being valid. - Parameter rename changes the URI template itself; anything that builds a URL or parses a template from the spec breaks.
Before changing anything, ask whether the spec needs to mirror the backend. A URI path segment is text on the wire; if the backend wants numerics, keep the spec type string with a pattern such as ^[0-9]+$, and coerce/validate in the flow. That gives the same guarantee without breaking consumers.
If the change is genuinely required: publish it as a new major version (v2) in Exchange, keep v1 published and marked deprecated with a sunset date, and route traffic by path or header version. Never mutate a consumed contract in place - the consumers' generated code and mocks are pinned to it.
3. Design the reuse mechanism for the `Error` type and the two headers so five APIs stay consistent.
Read the worked answer
- Create a separate RAML library project in Design Center (not an API project) holding a data type fragment for
Errorand trait fragments for the correlation-id and pagination headers. - Publish it to Exchange with a real semantic version, and reference it from each API with
uses: common: 1.0.0. - Use version ranges deliberately: pin exact versions for APIs in production, use ranges only where you control every consumer.
- Apply the traits at the method or resource level so the headers appear in every operation without copy-paste; a copy-pasted header that drifts between APIs is the failure mode you are avoiding.
- Treat the library as a contract: a breaking change to
Erroris a major version bump for the library and for every API that exposes it.
If the team uses OAS instead, the equivalent is shared components referenced by $ref from a published fragment; the discipline is identical, the tooling support in Design Center is weaker, so validate the mocking and Exchange publishing path first.