I diffed GitHub's, Stripe's and OpenAI's OpenAPI specs. Three vendors, three totally different change regimes.
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…
Three leading software companies, GitHub, Stripe, and OpenAI, each maintain publicly available OpenAPI specifications for their respective APIs. However, these specifications undergo significant changes over time, leading to different approaches in monitoring and adapting to these changes for developers and businesses that rely on them.
GitHub's OpenAPI specifications experience continuous modifications, with additions and removals of operations. In a recent six-month period, around 154 operations were added, and 8 were removed. Among the removed operations, six were part of the GitHub Classroom surface, and the seventh was related to the dependency graph. The main challenge in monitoring GitHub's API changes lies in the absence of a pinned version, making it difficult to predict when deprecated operations will be removed.
Therefore, developers must actively monitor GitHub's changelog to stay informed about potential impacts on their integrations.
In contrast, OpenAI's API specifications saw a 25% increase in operations over a ten-week period, with all 10 of the newly deprecated operations related to the /videos surface. Unlike GitHub, OpenAI does not pin callers to a specific version, and deprecated operations are simply flagged without a set shutdown date. This fast-paced change regime requires developers to closely monitor OpenAI's changelog to adapt their integrations promptly.
Stripe, on the other hand, takes a different approach by pinning every account to a specific dated API version. Accounts remain on their assigned version until explicitly upgraded. Over a five-month period, Stripe's OpenAPI specifications saw only seven new additions with no removals or deprecated operations. This versioning strategy minimizes the risk of unexpected changes to existing integrations, making Stripe's monitoring approach less critical compared to the other two companies.
In summary, these three companies demonstrate distinct change regimes in their OpenAPI specifications. GitHub undergoes continuous modifications with no version pinning, necessitating active monitoring of their changelog. OpenAI experiences rapid growth and deprecates entire product categories within a short timeframe, requiring developers to closely watch their spec for updates.
Stripe, however, pins accounts to specific versions, reducing the risk of unexpected changes and making monitoring a less urgent task. Each vendor presents a unique challenge for developers and businesses to adapt their integrations accordingly.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
