Build Backwards-Compatible REST APIs with Rolling Versions

Transcript

1. Build
   Backwards-Compatible
   REST APIs with Rolling
   Versions
   Subomi Oluwalana
   

   View Slide

2. Hi, 󰗜
   My name is Subomi Oluwalana, I’m a
   Software Engineer and the
   Co-Founder & CEO at Convoy.
   

   View Slide

3. Agenda
   1. Introduction
   2. Background
   3. What are Rolling Versions?
   4. The Golang Implementation
   5. References
   

   View Slide

4. Background
   

   View Slide

5. - 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.
   

   View Slide

6. 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.
   

   View Slide

7. Image Credits: Keygen.sh
   

   View Slide

8. Image Credits: Keygen.sh
   v1.1 request
   v1.1 response
   

   View Slide

9. 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
   

   View Slide

10. A quick
    example
    

    View Slide

11. Demo time!
    

    View Slide

12. The Golang Implementation
    github.com/subomi/requestmigrations
    

    View Slide

13. The Migration Map
    It maps all the
    transformations to
    their respective
    versions.
    

    View Slide

14. Registering Migrations
    Here’s the code from
    the previous
    example.
    

    View Slide

15. The Migration Interface
    Ensure to set the
    body back with a
    io.NopCloser
    

    View Slide

16. Configuring the Library
    Retrieve version
    from request
    header.
    Retrieve version
    from the database.
    

    View Slide

17. Usage
    Wrap specific
    request handlers
    only.
    Use as a
    middleware, wrap
    the entire router.
    

    View Slide

18. Instrumentation
    Outputs a prometheus histogram metric to debug transformation
    latencies and stale versions.
    

    View Slide

19. Instrumentation
    Todo: Add graphs.
    

    View Slide

20. Instrumentation
    Todo: Add graphs.
    

    View Slide

21. 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+
    

    View Slide

22. 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.
    

    View Slide

23. 1. Avoid N+1 Queries in your
    transformations.
    2. Monitor versioned request
    latencies.
    3. Perform end-to-end tests to
    verify correctness.
    

    View Slide

24. 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
    

    View Slide

25. @subomioluwalana
    @subomiOluwalana
    Subomi Oluwalana
    [email protected]
    

    View Slide