Incomplete Error Responses And Missing Write-Scope Explanation In Branching API OpenAPI Spec
11 of 12 branching endpoints document only 500 while API returns 401/403/429; GET /v1/branches/{id}/diff uniquely requires environment:write scope but docs don't explain why, causing generated clients to mishandle auth failures and integrators to request excessive permissions.
OpenAPI spec source for branching operations drifted: error response schemas were omitted during generation, and the GET diff endpoint's x-oauth-scope was set to environment:write without documenting the server-side shadow database provisioning rationale.
1. Download spec: curl -s https://api.supabase.com/api/v1-json -o spec.json
2. Run provided Python snippet to list documented 4xx/5xx per branching path; observe only 500 for 11 endpoints.
3. List GET operations with x-oauth-scope ending :write; observe only /v1/branches/{branch_id_or_ref}/diff.
4. Test live endpoint with invalid PAT, returns 401 and body {"message":"JWT could not be decoded"} while docs list only 500.
Fixing Code Block
import json
PATH = "spec.json"
with open(PATH) as f:
spec = json.load(f)
methods = {"get", "post", "put", "patch", "delete"}
required_errors = {
"401": {"description": "Unauthorized"},
"403": {"description": "Forbidden"},
"429": {"description": "Too Many Requests"},
}
for path, item in spec.get("paths", {}).items():
if "branch" not in path:
continue
for method, op in item.items():
if method not in methods:
continue
if path == "/v1/projects/{ref}/branches" and method == "delete":
continue # already correct
responses = op.get("responses", {})
for code, info in required_errors.items():
responses.setdefault(code, info)
op["responses"] = responses
for path, item in spec.get("paths", {}).items():
op = item.get("get")
if op and str(op.get("x-oauth-scope", "")).endswith(":write"):
op["description"] = (op.get("description", "") +
"\n\nRequires `environment:write` because diffing may provision a shadow database and apply schema server-side.")
op["x-oauth-scope-explanation"] = "Requires environment:write because diffing may provision a shadow database and apply schema server-side."
with open(PATH, "w") as f:
json.dump(spec, f, indent=2)
print("Spec updated")
Script adds 401/403/429 to all branching operations missing them (except already correct DELETE /v1/projects/{ref}/branches), and appends a description explaining why diff requires write scope. This aligns spec with actual API and matches other v1 operations, enabling generated clients to model auth failures.
Edge Case Audit
This patch modifies generated spec.json directly; if the source spec is regenerated from internal decorators, changes will be lost. Ensure upstream source is fixed or reapply in CI. Adding error responses may affect code generator output: confirm clients handle additional response classes; no breaking behavior expected. Rollback: restore original spec from backup or regenerate from unchanged source.
