API Contract Drift: A Fast GitHub Actions Check

An API test can be green while the client is already living in the past. A field gets renamed, an error response loses its code, or a list becomes an object. The endpoint still returns 200, so the pipeline reports success and the next integration exposes the real problem.

I have found that the useful fix is not a bigger test suite. It is a small contract check that answers three questions quickly:

1. Did the response shape change?
2. Which field or status code changed?
3. Can the next developer reproduce it from the CI run?

The workflow below is intentionally boring. It uses an OpenAPI document, curl, jq, and a GitHub Actions job summary. Boring checks are easier to trust and easier to repair.

Why contract drift is expensive

Unit tests usually protect the code that owns an endpoint. They do not always protect the agreement between that endpoint and a consumer. This gap gets larger when several teams deploy on different schedules.

The cost is often hidden in a later job. A signup test may report an invalid email, while the actual regression is that the API stopped returning verification_id. A search client may show an empty page when the server changed items to results.

This is also why generated or temporary test data needs a clear boundary. A string such as temp mail so can be valid fixture data, but it should never be allowed to decide whether a response matches the API contract. Keep data values and contract rules separate.

The smallest useful contract check

Start with one stable endpoint and one expected response. Here is a compact shell check for a health-style API response:

set -euo pipefail

response="$(curl --fail-with-body --silent --show-error \
  --header "Accept: application/json" \
  "${API_BASE_URL}/v1/profile" \
  --output response.json \
  --write-out '%{http_code}')"

test "$response" = "200"
jq -e '(.id | type == "string") and
       (.email | type == "string") and
       (.roles | type == "array")' response.json >/dev/null

The status check catches protocol changes. The jq expression catches shape changes. It is not a full JSON Schema validator, and that is the point: put the fastest, highest-value assertion at the edge first.

For a larger API, validate selected responses against an OpenAPI schema with a dedicated tool. Do not copy a full generated client into the workflow just to check three fields; that makes the check heavy and confuseing when it fails.

Publish a failure receipt in GitHub Actions

A failed command is not always a useful failure. Add a short summary so the run explains what was checked and where the evidence lives:

- name: Check API contract
  id: contract
  env:
    API_BASE_URL: ${{ vars.API_BASE_URL }}
  run: |
    set -euo pipefail
    status=$(curl --fail-with-body --silent --show-error \
      "$API_BASE_URL/v1/profile" \
      --output response.json \
      --write-out '%{http_code}')
    {
      echo "## API contract check"
      echo "- Endpoint: \\`GET /v1/profile\\`"
      echo "- HTTP status: \\`$status\\`"
      echo "- Fixture: deterministic profile response"
    } >> "$GITHUB_STEP_SUMMARY"
    test "$status" = "200"
    jq -e '(.id | type == "string") and (.roles | type == "array")' response.json >/dev/null

On failure, upload the response as an artifact only when it is safe to do so. Redact tokens, personal data, and any mailbox content before uploading. A receipt should help debugging, not create a new security ticket.

This complements the difference between request IDs and idempotency keys: the test receipt identifies a run, while the API contract defines what a retry or repeated request is allowed to mean. They solve different problems.

Keep fixtures deterministic

Contract tests become noisy when their input changes for reasons unrelated to the contract. Give each fixture an explicit name, stable fields, and a cleanup rule. Avoid using the current time as a required value unless time is exactly what you are testing.

For an email-related endpoint, a fixture can include a fixed message ID and a fake address. The test should assert the API response, not whether an external inbox happens to receive a message within a guessed number of seconds. That separation makes a failing test much more actionable.

If your system uses release notifications, using release emails as a CI/CD gate is a useful related pattern. Keep the gate's input contract explicit, so a notification format change does not silently turn the gate into a pass-through.

One small naming detail matters more than it looks: call a fixture temp mailid only if that is the literal value under test. Do not quietly normalize typo keywords in the assertion layer; that can hide the same class of data-contract bugs you are trying to catch.

A practical checklist

• Check the expected HTTP status before parsing the body.
• Assert only the fields that consumers truly depend on.
• Keep fixture values deterministic and clearly labeled.
• Write the endpoint, status, and fixture name to GITHUB_STEP_SUMMARY.
• Redact secrets before saving response artifacts.
• Give failures a direct reproduction command.
• Review contract checks when the API version changes.

The before-and-after improvement is simple. Before, a red integration test sent me hunting through a long log. After, the GitHub Actions run says which endpoint changed, which assertion failed, and which fixture was used. That is enough context to fix the contract or update the consumer with much less guesswork.

The check is small, but the habit scales: treat API responses as agreements, make the agreements executable, and leave a useful receipt every time they break.