Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Build Backwards-Compatible REST APIs with Rolling Versions

Build Backwards-Compatible REST APIs with Rolling Versions

This is the slide to the talk I gave at SysConf 2023 by SysDsgn.

Subomi Oluwalana

September 16, 2023

More Decks by Subomi Oluwalana

Other Decks in Programming


  1. Hi, 󰗜 My name is Subomi Oluwalana, I’m a Software

    Engineer and the Co-Founder & CEO at Convoy.
  2. Agenda 1. Introduction 2. Background 3. What are Rolling Versions?

    4. The Golang Implementation 5. References
  3. - Improve the REST API without breaking old integrations. -

    Common wisdom is semantic versioning - /api/v1, /api/v2 - Incentivises big-bang changes. - Splits user base between versions. - We believe infrastructure should be boring. - Enter Rolling Versions.
  4. What are Rolling Versions? Rolling Versions is an API versioning

    technique that ensures backward-compatibility by applying request and response transformation to each user request using change objects.
  5. A quick example In this example, we describe an API

    used to retrieve a list of user objects, with the date versioning scheme. Versions - Initial Version - 2023-04-01 - 2023-05-01
  6. Limitations httptest.ResponseRecorder - Designed for the test environment. - Enabled

    Quick Prototyping. - Backwards Compatible with Handlers. - Works with early versions of Go. http.ResponseController - Designed for regular production code. - Might not be Backwards Compatible with your Handlers. - Works with only Go 1.20+
  7. Parting thoughts - Some changes to the API are much

    more complex than response transformations. See Changes with side effects in the Stripe article. - Handling arbitrary data migrations, e.g. Webhook payloads.
  8. 1. Avoid N+1 Queries in your transformations. 2. Monitor versioned

    request latencies. 3. Perform end-to-end tests to verify correctness.
  9. References - Rails Implementation - github.com/keygen-sh/request_migrations - Laravel Implementation -

    github.com/tomschlick/request-migrations - Backwards–compatibility in Cloudflare Workers - blog.cloudflare.com/backwards-compatibility-in-cloudflare-workers - Infrastructure should be boring - dragonflydb.io/blog/infrastructure-should-be-boring - APIs as Infrastructure: future-proofing Stripe with versioning - stripe.com/blog/api-versioning