Real-Life REST API Versioning Hands on! Alexandre TOURET

No content

The Bookstore API

The context diagram

Under the hood

No content

Let's version this API

Alexandre TOURET Software Architect, Developer Advocate @touret_alex blog.touret.info alexandre-touret Who am I?

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

What about API versioning?

What is it versioned? We only version API contract breaking changes (operations or data/fields)

No content

✓ 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

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

Workshop

• 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

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

You will learn in this chapter: • How to start the platform • H ’ API contract Chapter 1 How to upgrade your API without versioning?

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

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

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

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

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

Code & configuration

Main Feature Hotfix Develop Release V1 V2 V2.1 Release with the list of authors Backward compatibility V1.1

Configuration management

Authorization

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

Explore our jobs in tech: careers.worldline.com Want to shape how the world pays and get paid?