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

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

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

Alexandre Touret

December 04, 2023

More Decks by Alexandre Touret

Other Decks in Programming


  1. • 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
  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. 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?
  4. 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
  5. 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?
  6. If you want to use URL Versioning → put the

    version in the URI If you want to postpone it /v1/api/books
  7. • 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
  8. • 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
  9. • 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?
  10. ├── │ └── 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
  11. • 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
  12. Authorization policy V1 Bookstore admin Bookstore customer Users Roles Permissions

    Books/write Books/search Isbns/read Isbns/write Books/read Admin Search Read
  13. 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
  14. For your next APIs Avoid it first Identify breaking changes

    Work on the modularity Observe! Consider the big picture Communicate!
  15. 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