Apidays Paris 2023 - Software and APIs for Smart, Sustainable and Sovereign Societies December 6, 7 & 8, 2023 Real-Life REST API Versioning: Strategies and Best Practices Alexandre Touret, Software Architect at Worldline ------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/

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?