{"slug": "i-diffed-github-s-stripe-s-and-openai-s-openapi-specs-three-vendors-three-change", "title": "I diffed GitHub's, Stripe's and OpenAI's OpenAPI specs. Three vendors, three totally different change regimes.", "summary": "A developer diffed the OpenAPI specs of GitHub, Stripe and OpenAI across recent commit windows, finding three distinct change regimes: GitHub removed 8 operations and newly deprecated 7 (six of them the entire GitHub Classroom surface) with no version pinning to protect callers, OpenAI deprecated all 10 operations of its /videos surface in about ten weeks, while Stripe removed and deprecated nothing across two dated API versions. The author notes that Stripe's stability stems from pinning accounts to dated API versions, making spec changes upgrade impact rather than incident risk, and that OpenAI's spec flags deprecation without encoding a shutdown date.", "body_md": "Every vendor with a public API publishes, somewhere, an OpenAPI document describing its exact shape. Fewer people actually diff it commit to commit. I did — for three vendors a lot of us depend on, GitHub, Stripe and OpenAI — over the most recent stretch each has on record. The three specs don't just change at different speeds. They change in three genuinely different ways, and only one of those ways is safe to ignore.\n\nMethod: for each vendor, two commits of their spec repository — a baseline and a current one — counted operations, and looked at what was removed or newly marked deprecated between them. The commit shas are below so you can reproduce this yourself: clone the repo, check out both commits, diff.\n\nRepository: [`github/rest-api-description`](https://github.com/github/rest-api-description). Baseline `f7af1e5` (12 March 2026) against current `29bcb55` (16 September 2026) — a bit over six months.\n\nThe 8 removed operations fall into three groups: the Dependabot repository-access endpoints (list, patch, and set the default level), two Copilot metrics endpoints (org-level and team-level), and the issue-field-values endpoints (create, replace, delete). All eight were present at the baseline commit and absent at the current one. Two sampled commits tell you that much and no more: they don't tell you whether a removal was announced in between, which is exactly the problem if the spec is the only notice you get.\n\nThe 7 newly deprecated operations are almost entirely one thing: six of them are the entire GitHub Classroom surface — `GET /classrooms`, `GET /classrooms/{classroom_id}`, `GET /classrooms/{classroom_id}/assignments`, and the `/assignments/{assignment_id}` family (itself, its accepted-assignments list, and its grades). The seventh is `GET /repos/{owner}/{repo}/dependency-graph/sbom`.\n\nGitHub doesn't pin callers to a version. There's no dated release you're safely a few behind. The specification itself is the change log: an operation gets marked deprecated, then later it's gone, and the only signal in between is whatever you're watching yourself.\n\nRepository: [`openai/openai-openapi`](https://github.com/openai/openai-openapi). Baseline `db3e531` (16 July 2026) against current `7de0436` (22 September 2026) — about ten weeks.\n\nAll 10 are the entire `/videos` surface: create, list, retrieve, retrieve content, edit, extend, remix, delete, plus the two `/videos/characters` operations. Every operation under that path, deprecated in the same window.\n\nOne thing worth being precise about: `/assistants` (5 operations) was *already* deprecated at the baseline commit, not newly deprecated in this window. It doesn't belong in the count above, and I'd be overstating the finding if I folded it in.\n\nAnother: OpenAI's own spec marks an operation deprecated but doesn't encode a shutdown date, so \"deprecated\" here means \"flagged,\" not \"a date is set.\" And a vendor-support note — I measured OpenAI's spec with the same commit-diff approach used for the other two, but OpenAI isn't one of the two vendors the CI check described at the end of this piece actually supports yet. The numbers are real and reproducible; the tool doesn't run against this vendor today.\n\nRepository: [`stripe/openapi`](https://github.com/stripe/openapi). Baseline `cfe95bf` (17 March 2026, API version `2026-03-25.dahlia`) against current `30d3391` (26 August 2026, API version `2026-08-26.dahlia`) — about five months.\n\nFive months, two dated API versions apart, nothing taken away or flagged for removal. That's not a quiet period — it's the design. Stripe pins every account to a dated API version and keeps serving that version until you explicitly upgrade. A change landing in the spec is a question about what you'd get *if you upgraded*, not a warning about what's about to happen to you while you sit still. That's why a Stripe finding should read differently from a GitHub one: it's upgrade impact, not incident risk.\n\n|  | GitHub | Stripe | OpenAI | \n|---|---|---|---|\n| Window | ~6 months | ~5 months | ~10 weeks | \n| Operations | 1093 → 1239 | 587 → 594 | 281 → 352 | \n| Removed | 8 | 0 | 0 | \n| Newly deprecated | 7 | 0 | 10 | \n| Versioning | none — the spec is the notice | pinned per account | none | \n\n\"Watch the vendor's changelog\" isn't one practice, it's three. For Stripe it means watching for a version you might one day adopt. For GitHub it means watching a spec that moves under you with no pin to hide behind. For OpenAI, on this evidence, it means watching a surface that's both growing fast and willing to deprecate an entire product category inside a quarter. Only Stripe's version of \"watch it\" is safe to skip while you stay on your pinned version. The other two aren't.\n\nNone of this needed a new diffing tool. [`oasdiff`](https://github.com/oasdiff/oasdiff) already compares two OpenAPI documents field by field, and it does it well — credit, not a pitch, there's no reason to reinvent that. The hard part, if you actually ship against these APIs, is smaller and more tedious than a diff: of GitHub's 15 removed-or-newly-deprecated operations above, the only question that matters to *you* is whether any of them is one you call. If you don't touch Dependabot's repository-access endpoints, Copilot metrics, or GitHub Classroom, those 15 changes are noise. The other 154 additive operations in that same window aren't your problem either — nobody's build breaks because a vendor added something new.\n\nThat's a filter, not a diff. A full spec diff against an active vendor like GitHub runs to hundreds of changes most weeks. The number that matters to a given integration is usually zero, occasionally one, and the gap between \"zero\" and \"did anyone check\" is the entire reason to automate this instead of skimming a changelog by eye.\n\nOne more thing worth saying plainly, because a monitor that always finds something is suspicious: I looked at Twilio's `api_v2010` spec over a comparable window and it didn't change a single operation in six months. A tool that reported findings against that spec anyway would be manufacturing noise, so it's deliberately left out of what I cover.\n\nThat filter is [APIBreak](https://apibreak.dev). You declare the vendor endpoints your code actually calls in a small JSON manifest, pin a baseline commit or date, and it runs the same kind of comparison as above — but reports only your declared endpoints, with everything else counted and left out of the list. `npx apibreak check --manifest apibreak.json` in CI, exit code 2 on a finding at or above `--fail-on`, a GitHub Action wrapper, MIT-licensed, no credentials and no repository access beyond the checkout your workflow already has. It supports `github` and `stripe` today; OpenAI isn't wired in. It ships as the npm package [`apibreak`](https://www.npmjs.com/package/apibreak).\n\nIt's new. I built it, and it has no users yet — I'm not going to pretend otherwise.\n\n*Written with AI assistance. The vendor numbers above are machine-generated from the commit shas cited in each section and are reproducible by diffing those commit pairs yourself.*", "url": "https://wpnews.pro/news/i-diffed-github-s-stripe-s-and-openai-s-openapi-specs-three-vendors-three-change", "canonical_source": "https://dev.to/skyblueballykid/i-diffed-githubs-stripes-and-openais-openapi-specs-three-vendors-three-totally-different-3pe1", "published_at": "2026-09-23 08:34:55+00:00", "updated_at": "2026-09-23 08:58:34.579123+00:00", "lang": "en", "topics": ["developer-tools", "ai-products", "ai-tools"], "entities": ["GitHub", "Stripe", "OpenAI", "GitHub Classroom", "Dependabot", "Copilot", "github/rest-api-description", "openai/openai-openapi"], "alternates": {"html": "https://wpnews.pro/news/i-diffed-github-s-stripe-s-and-openai-s-openapi-specs-three-vendors-three-change", "markdown": "https://wpnews.pro/news/i-diffed-github-s-stripe-s-and-openai-s-openapi-specs-three-vendors-three-change.md", "text": "https://wpnews.pro/news/i-diffed-github-s-stripe-s-and-openai-s-openapi-specs-three-vendors-three-change.txt", "jsonld": "https://wpnews.pro/news/i-diffed-github-s-stripe-s-and-openai-s-openapi-specs-three-vendors-three-change.jsonld"}}