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

Transcript

1. Real-Life REST API Versioning Hands on! Alexandre TOURET
3. The Bookstore API
4. The context diagram
5. Under the hood
7. Let's version this API
8. Alexandre TOURET Software Architect, Developer Advocate @touret_alex blog.touret.info alexandre-touret Who am I?
9. 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
10. What about API versioning?
11. What is it versioned? We only version API contract breaking changes (operations or data/fields)
13. ✓ 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
14. https://cloud.google.com/blog/products/api-management/common- misconceptions-about-api-versioning?hl=en https://docs.github.com/en/rest/overview/api-versions?apiVersion=2022- 11-28 Going further
15. Workshop
16. • 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
17. The workshop & the solution https://github.com/alexandre-touret/rest-apis-versioning-workshop https://github.com/alexandre-touret/rest-apis-versioning-solution 2H_WORKSHOP branch
18. You will learn in this chapter: • How to start the platform • H ’ API contract Chapter 1 How to upgrade your API without versioning?
19. 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
20. 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
21. 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
22. 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
23. 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
24. Code & configuration
25. Main Feature Hotfix Develop Release V1 V2 V2.1 Release with the list of authors Backward compatibility V1.1
26. Configuration management
27. Authorization
28. 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
29. Explore our jobs in tech: careers.worldline.com Want to shape how the world pays and get paid?