Working AtlasAPI design & compatibility

Contract Change Bench

Change a JSON response and check whether an existing client can still use it.

TrySet Unknown response fields to Reject and inspect the added-field result.

Watch forIgnore accepts the added timezone field; Reject makes the example decoder refuse it.

Separate teaching model

The linked story describes related work; the scenarios and results here are synthetic.

Interactive model

A made-up JSON response lets you inspect one practical question: can an existing client keep working after its API producer changes? No production endpoint is called, and these examples do not describe a specific project API.

Change the producer's response

Response change

Unknown response fields

Unknown status values

“Ignore” tolerates an unfamiliar response property; “Reject” models a closed response schema. Real clients may follow different rules.

BEFORE → AFTER

One response, one change

Existing response

{
  "id": 104,
  "displayName": "Mira",
  "status": "active"
}

Changed producer

{
  "id": 104,
  "displayName": "Mira",
  "status": "active",
  "timezone": "Asia/Calcutta"
}

Example client result

Accepts response

Outcome under the selected unknown-field policy

WHY

The existing client can keep reading this response.

The client reads id, displayName, and status, then ignores the new timezone property.

The example client reads id, displayName, and status. A different client, validation policy, or versioning strategy can change the result.

Further reading: Google AIP-180 on API backward compatibility. It covers broader API-evolution rules than this small response-only model.

Preparing the interactive experiment…

Skill practicedChange APIs without surprising existing clients

Connection to my workProcedure work included secure REST API delivery; this invented response illustrates client compatibility risks.

Understand the result

Change one made-up JSON response and compare it with a fixed existing client that reads id, displayName, and status. Choose how that client treats unfamiliar properties and status values. The result is limited to this response example; it is not an API compatibility checker or a test of any production endpoint.

Controls

Response change: Choose an optional-field addition, a removal or rename of a field the old client reads, a new status value, or a change in the type of id.
Unknown response fields: For the added-property scenario, choose whether the old client ignores an unfamiliar property or rejects it. This setting is disabled for changes to fields the client already reads and for new status values.
Unknown status values: For the new-status scenario, choose whether the old client accepts an unrecognized status value or rejects it. This setting is disabled for property and consumed-field changes.

What to watch for

Ignore accepts the added timezone field; Reject makes the example decoder refuse it.
Add a status value. A client that tolerates unknown values can keep reading the response, while a closed enum check rejects it.
Remove or rename displayName, or change the type of id. The fixed old client depends on the original field and type, regardless of the two parser settings.

Why it happens

Compatibility is a relationship between a producer change and the clients that consume it. Whether an added field or enum value is safe depends on how existing clients validate and interpret responses; removing, renaming, or changing a consumed value can break those clients. Real API versioning also considers requests, defaults, error behavior, generated clients, and rollout order, all outside this response-only model.

How this idea relates to the linked work

My Procedure experience records building secure REST APIs. This synthetic exercise makes one review question tangible: what does a producer-side response change mean for a client that already exists? Its example fields and parser policies are invented for teaching; it neither calls nor describes a specific production endpoint.

See the broader engineering brief