API versioning
API versioning keeps old clients working while the API changes. Release 6.0 changed the order fields, and 150 of 500 orders/s still came from version 5. Each live version runs on its own handler, and each client goes to the handler that it can talk to.
See it on the board
The same traffic runs on two boards. The simulator measured both when this page was built.
| Measure | Goal | One handler for 6.0 only | A handler for each version |
|---|---|---|---|
| Error rate (*) | under 0.1% | 0% Pass | 0% Pass |
| p99 latency (New) | under 150 ms | 80 ms Pass | 79 ms Pass |
| p99 latency (Old) | under 150 ms | 79 ms Pass | 71 ms Pass |
| Monthly cost | 32 USD/mo | 36 USD/mo | |
| Error rate | 0% | 0% | |
| Level rules | none broken | Board is not complete Fail | Pass |
Key numbers
| Number | Value |
|---|---|
| Requests per second, one Node API | 10,000 ops/s |
| Node API call, median | 1 ms |
| Default pool size, one API replica | 20 connections |
Canary · 5% of requests fail for 15 seconds · 750 failed requests
How it works
A web page updates when you reload it. A phone app does not. Users keep old versions for weeks, and some never update. When the API changes, the old apps still send the old format.
In the mini board release 6.0 changed the order fields. The new handler cannot read what app 5.x sends. After the release, 150 of the 500 orders/s still come from 5.x. The level rule says that each live version must run on its own handler, and a board that sends the old traffic to the new handler breaks it.
Versioning gives each live version a handler of its own. The router looks at the version of each request, for example in the path or a header, and sends it to the handler that understands it. Both versions work at the same time.
Two handler fleets share one database, so their connection pools must fit its limit. In the mini board the database allows 100 connections, so the new handler's pool shrinks from 24 to 20, and the old handler gets 16.
Retire a version only when its traffic is gone: watch the share of each version, tell the users to update, and then remove the handler. Keep changes compatible when you can, for example by adding fields and not renaming them.
In the levels you run both versions and keep errors and p99 inside their limits.