An API contract

Play this lesson

One rename, every phone

Remy renames a field on the server from seeds to seedCount. Every Shard Garden app already installed on a phone still reads seeds, and crashes.

An API (application programming interface) is how one program asks another for something. An API contract is the written promise of exactly what each request and each answer looks like.

OpenAPI

The OpenAPI Specification "defines a standard, programming language-agnostic interface description for HTTP APIs". An OpenAPI document, written in JSON or YAML, lists every path, what it takes and what it returns.

Tools read that one file and make documentation, tests and client code from it.

Quick check

Why did Remy's rename of seeds to seedCount crash the installed apps?

  1. The apps still read seeds, so the server broke its contract
  2. Phones cannot read JSON
  3. The server ran out of memory
Show the answer

The apps still read seeds, so the server broke its contract

The installed apps were built against the old contract. The server changed its side of the promise without them.

Read the contract

openapi.yaml
paths: /gardens/{id}:  get:   responses:    '200':     description: A garden     content:      application/json:       schema:        $ref: garden.yaml

What does this part of the contract promise?

  1. A GET to /gardens/{id} answers 200 with a Garden, as JSON
  2. It creates a new garden
  3. It deletes every garden
Show the answer

A GET to /gardens/{id} answers 200 with a Garden, as JSON

get is the method, 200 is the success code, and the schema points to the Garden shape, defined in garden.yaml.

Contract first

The team changes the contract first, reviews it, then both sides build to it. A test checks that the server's real answers match the contract, so a renamed field fails in CI, not on players' phones.

Adding is safe, removing is not

Adding a new optional field is usually safe: an app written to ignore fields it does not know carries on. Removing or renaming a field breaks every app that reads it.

So the safe way to rename is to add the new field, keep sending the old one, and remove it only when no app reads it.

Quick check

Adding a new optional field to a response is usually safe for apps already installed.

Show the answer

True

Apps that ignore unknown fields keep working. That is why apps are written to skip what they do not understand.

When a change must break

Sometimes the old shape is simply wrong and has to go. Then the API needs a new version, and a plan for the apps still using the old one.

Bolt says: Next: versioning an API.

Fact-checked 12 October 2026