Detect Sume API changes in CI: diff the live OpenAPI document

A document that cannot go stale

Sume serves its OpenAPI document live at https://api.sume.com/reference/json, and the interactive reference reads from the same place. If you hand-write a client, that document is the closest thing to a contract you can check automatically. A scheduled CI job that reads it and compares to a committed copy tells you about a new, renamed or removed route before a user does.

Diffing the entire document would be noisy. Reduce it to one line per operation: the HTTP method and the path.

The reduction

This writes routes.txt from the live spec. The paths object maps each path to its operations; the filter keeps only keys that are HTTP methods.

curl -fsS https://api.sume.com/reference/json \
  | jq -r '.paths | to_entries[]
      | .key as $p | .value | keys[]
      | select(IN("get","post","put","patch","delete"))
      | ascii_upcase + " " + $p' \
  | LC_ALL=C sort > routes.txt

The check

Commit a baseline as api-routes.baseline.txt, then in CI run the command above and compare:

diff -u api-routes.baseline.txt routes.txt || {
  echo "Sume API route list changed; review and update the baseline"; exit 1; }

How to use the signal

• A new route is information; a removed one is the one that should page a human.
• The legacy /v1/video-1.0/generate route is documented as retiring, so a diff that removes it is one to plan for rather than a surprise.
• Run it on a schedule as well as on pull requests, since the document changes without your commits.
• Do not use the diff to decide request shapes at runtime; regenerate the SDK or update your client deliberately.