UPDATE 11/28/2022 - six months after publishing this post GitHub made this announcement: To infinity and beyond: enabling the future of GitHub’s REST API with API versioning.
"If you have an integration with the REST API, you should update it now to start sending the X-GitHub-Api-Version header."
No version 👏 No service. 👏
When providing recommendations we like to use examples of great companies, the decisions they made — that often go against the grain, and why they made those decisions. One of my favorite examples of this is the fact that the best API companies tend to use API keys.
But what about great companies getting it wrong?
We recently wrote recommendations for versioning your API and had one primary piece of advice - insist that the client includes the desired version on every request.
It’s simple: No Version? No Service.
When giving examples of great APIs, I have a few ‘go-tos’:
| API | API Keys? | Require Version? | URL-based version |
|---|---|---|---|
| Stripe | ✅ | ✅ | ✅ |
| AirTable | ✅ | ✅ | ✅ |
| Twilio | ✅ | ✅ | ✅ |
| SendGrid | ✅ | ✅ | ✅ |
| GitHub | ✅ | ❌ | ❌ |
You’ll notice one anomaly here though - the GitHub API doesn’t use URL-based versioning and doesn’t require a version. Let’s quote their docs
When using the REST API, we encourage you to request v3 via the
Acceptheader
Note the use of the word ‘encourage’, there’s more
Important: The default version of the API may change in the future. If you're building an application and care about the stability of the API, be sure to request a specific version in the
Acceptheader as shown in the examples below.
Source: Getting started with the REST API
This approach is asking for trouble and limits your options. It’s hard to run multiple versions of your API simultaneously (without defaulting to the old one 🤮) and it’s hard to know which customers are trying to use which version of your API. Maybe you can tell because of all the support calls and errors they’re getting?
That’s why we tend to recommend URL-based versioning - it’s implicit in the address of the URL what version the client is coded to consume and it can’t be skipped, lest you’ll get a 404. It’s good enough for Stripe, AirTable, and the Twilio family so it’s probably good for you.
If you do decide to go the headers route, be sure to send back a 400 if you don’t see an explicit version requested. Your error message could be “No version, no service" - that one’s on us.
