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

[NDCLondon24] Real-Life REST API Versioning Hands on!

Alexandre Touret
January 31, 2024

[NDCLondon24] Real-Life REST API Versioning Hands on!

When we want to publish APIs, for instance using an API (Application Programmable Interface) Management solution, we regularly think about versioning.

This practice meets project management needs but brings a lot of complexity.
Imagine, you work on a platform which exposes APIs to many customers.

You must bring new features while controlling the existing ones.

How to deliver new functionalities to specific customers without affecting the others?

Throughout this workshop you will (re)discover and apply advice I have put in place and helped me during my last projects.

Through a real-life use case based on a microservices architecture, we will define the best strategy to put in place, the other potential ones and their constraints.

We will challenge them implementing new features for a new customer in this application.

At the end of this workshop, we will have the big picture and put into practice diverse ways of APIs versioning.

Alexandre Touret

January 31, 2024

More Decks by Alexandre Touret


  1. We design payments technology that powers the growth of millions

    of businesses around the world. 7000+ engineers in over 40 countries Managing 43+ billion transactions per year €250M R D every year Handling 150+ payment methods
  2. ✓ adding an operation ✓ adding an optional parameter ✓

    adding an optional request header ✓ adding a response field ✓ adding a response header ✓ adding enum values ✓ removing an entire operation ✓ removing or renaming a parameter ✓ removing or renaming a response field ✓ adding a new required parameter ✓ making a previously optional parameter required ✓ changing the type of a parameter or response field ✓ removing enum values ✓ adding a new validation rule to an existing parameter ✓ changing authentication or authorization requirements Changes according GitHub https://docs.github.com/en/rest/overview/api-versions?apiVersion=2022-11-28 Breaking Non-breaking
  3. • See what is a non breaking change and the

    impacts • Setup a URL versioning and a Header versioning and see the impacts • Modify configuration to take versioning into account • Add a breaking change • Strive for backward compatibility between the V1 and the V2 • Enforce versioning authorization with scopes Topics covered
  4. You will learn in this chapter: • How to start

    the platform • H ’ API contract Chapter 1 How to upgrade your API without versioning?
  5. You will learn in this chapter: • The impacts of

    the versioning in the OPENAPI Description file • Implement a URL Based versioning • Implement a header-based versioning • Deploy and configure a default version for your API Chapter 2 Your first version
  6. You will learn/do in this chapter: • Create a new

    version (it will be a copy of the rest-book module) • Add a new breaking change functionality to the last version Chapter 3 Your second version
  7. You will learn/do in this chapter: • Pinpoint Configuration management

    issues due to API Versioning • Exposing the two versions on the API Gateway Chapter 4 Configuration management
  8. You will learn/do in this chapter: • Dig into Backward

    compatibility hassle and implement a solution to make both of the two versions work Chapter 5 Dealing with breaking changes
  9. You will learn/do in this chapter: • Pinpointing the impacts

    on authorization • Enforcing API versions restrictions with OAUTHv2 scopes Chapter 6 Security and authorization impacts
  10. Main Feature Hotfix Develop Release V1 V2 V2.1 Release with

    the list of authors Backward compatibility V1.1
  11. D ’ ! Follow & get in touch @touret_alex linkedin.com/in/atouret

    blog.worldline.tech @WorldlineTech Follow our tech team: Follow me: blog.touret.info alexandre-touret Feedback