[APIDAYS23] Real-Life REST API Versioning Strategies & Best Practices

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.

Which strategy to adopt? What are the potential technical tools and practices we could implement easily?

During this presentation, you will (re)discover advice that 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.

At the end of this presentation, we will have the big picture on the diverse ways of APIs versioning.

Transcript

1. Real-Life REST API Versioning Strategies & Best Practices 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.
10. Delivery CI/CD Code management Security Backward compatibility Potential impacts
11. Hold on! What about the V1?
12. • Do I really need to version this API? • How to handle versioning? • How many versions can I handle at the same time? • Is my platform compatible with? • What are the impacts on my configuration? • What about security & authorization mechanisms? Some questions to ask to yourself
13. One deprecated O “ ” version How many versions at once?
14. What is it versioned? We only version API contract breaking changes (operations or data/fields)
15. ✓ 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
16. A breaking change in the API contract e.g.,: In the Book object, the author field moves to a list of authors So what ? What is a breaking change?
17. What about non-breaking changes? Non-breaking changes can be applied without versioning
18. Adding operations & fields
19. How to handle versioning? URL Exemple /v1/api/books HTTP Header Exemple X-API-VERSION : v1 Content-Type Exemple Accept: application/vnd.myn ame.v1+json RFC 9110
21. URL specification versioning Versions evolve through breaking changes URL specification versioning It sticks to the V1 Header specification versioning "X-GitHub-Api-Version” What about GAFAM & co?
22. If you want to use URL Versioning → put the version in the URI If you want to postpone it /v1/api/books
24. When a new customer brings new functionalities
26. The main functionality of the V2 Author list management V2 V1
27. API contract Database Backward compatibility with the V1 Impacts
28. V2 V1 V2 V1
29. From source code up to production
31. • Adapt the code source to deliver at the same time many versions Source code management • JAR, ZIP, Helm charts, Docker images One deliverable per branch/tag • Dynamic: Configuration server • Static: Config Maps Configuration • Databases Scripts Impacts
32. • Pinpoint who uses your API • Publish and use dashboards (e.g., Kibana) • Use an API-KEY to clearly identify your customers Observability → Define the best strategy → Better anticipate the decomissioning of your deprecated APIs
33. • Unify and handle the version management by an API Gateway One runtime per version
34. • The API Gateway exposes both the two versions (V1 & V2) • It transforms requests and responses from the V1 to V2 format If we only deploy the latest service?
35. ├── │ └── touret │ └── │ └── │ ├── │ │ ├── 1 │ │ ├── 2 │ │ ├── dto │ │ ├── y │ │ ├── │ │ ├── │ │ ├── y │ │ └── Handle versioning in the code base 1 version = 1 package Let the application deal w/ version handling ├── │ └── touret │ └── 1 │ └── 2
36. • Share your strategy to all the stakeholders • Draft your roadmap and changelogs on a regular basis • Use HTTP responses headers to indicate your API is deprecated Communication Deprecation: version="v1" Link:https://developer.example.com/deprecation
37. Authorization management
38. Authorization policy V1 Bookstore admin Bookstore customer Users Roles Permissions Books/write Books/search Isbns/read Isbns/write Books/read Admin Search Read
39. A new policy (V2) Bookstore Admin Bookstore customer Users Roles Permissions Books/search Isbns/read Books/write Isbns/write Books/read Authors/write Authors management admin
40. V2 V1
41. Enforce your versioning with scopes
42. We may have authorization policies update breaking changes D ’ y To sum up BookAdmin_V1
43. Wrap up
44. For your next APIs Avoid it first Identify breaking changes Work on the modularity Observe! Consider the big picture Communicate!
45. 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
46. Explore our jobs in tech: careers.worldline.com Want to shape how the world pays and get paid?