The `dispatches` API should return the run ID · community · Discussion #9752

2 min read Original article ↗

This argument only works if you treat API contracts as a matter of personal interpretation.

Once an API publishes an OpenAPI schema and encourages typed clients, the schema is the contract. Individual views about whether "fixating on 204 has merit" are irrelevant. Semantics are not subjective. 204 No Content is an explicit guarantee that no response body exists, and clients are correct to rely on that guarantee for typing, parsing, and control flow.

Changing that to 200 OK with a body is not "adding information". It is changing the contract. Status codes are not decoration. They are part of the observable behavior that real systems key off of. Control flow, retries, deserialization, and SDK behavior all hinge on that distinction.

Calling clients that relied on the published contract "poorly written" inverts responsibility. Those clients did the correct thing. They trusted the spec GitHub itself published and promoted. If the spec is optional, then it is not a contract at all, just documentation cosplay.

The "just check any 2xx" argument only holds in trivial clients. In CI and infrastructure automation, exact semantics are the whole point. These calls sit on the critical path for deploys, rollbacks, and production changes. Being precise here is not pedantry, it is table stakes.

Ergonomics do not override contracts. If you want to change semantics, version them or gate them. If you want to add data, do so without invalidating existing assumptions. Anything else is just redefining "additive" to mean "we already shipped it".

This thread exists because people are trying to integrate GitHub Actions reliably from outside GitHub. The problem was never taste or style. The problem was that the API made correlation impossible, then fixed it in a way that violated its own guarantees.

Individual views are not what govern behavior here. The contract does.