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

Slide 1

Slide 1 text

Real-Life REST API Versioning Strategies & Best Practices Alexandre TOURET

Slide 2

Slide 2 text

No content

Slide 3

Slide 3 text

The Bookstore API

Slide 4

Slide 4 text

The context diagram

Slide 5

Slide 5 text

Under the hood

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

Let's version this API

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

We design payments technology that powers the growth of millions of businesses around the world.

Slide 10

Slide 10 text

Delivery CI/CD Code management Security Backward compatibility Potential impacts

Slide 11

Slide 11 text

Hold on! What about the V1?

Slide 12

Slide 12 text

• 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

Slide 13

Slide 13 text

One deprecated O “ ” version How many versions at once?

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

✓ 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

Slide 16

Slide 16 text

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?

Slide 17

Slide 17 text

What about non-breaking changes? Non-breaking changes can be applied without versioning

Slide 18

Slide 18 text

Adding operations & fields

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

No content

Slide 21

Slide 21 text

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?

Slide 22

Slide 22 text

If you want to use URL Versioning → put the version in the URI If you want to postpone it /v1/api/books

Slide 23

Slide 23 text

No content

Slide 24

Slide 24 text

When a new customer brings new functionalities

Slide 25

Slide 25 text

No content

Slide 26

Slide 26 text

The main functionality of the V2 Author list management V2 V1

Slide 27

Slide 27 text

API contract Database Backward compatibility with the V1 Impacts

Slide 28

Slide 28 text

V2 V1 V2 V1

Slide 29

Slide 29 text

From source code up to production

Slide 30

Slide 30 text

No content

Slide 31

Slide 31 text

• 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

Slide 32

Slide 32 text

• 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

Slide 33

Slide 33 text

• Unify and handle the version management by an API Gateway One runtime per version

Slide 34

Slide 34 text

• 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?

Slide 35

Slide 35 text

├── │ └── 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

Slide 36

Slide 36 text

• 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

Slide 37

Slide 37 text

Authorization management

Slide 38

Slide 38 text

Authorization policy V1 Bookstore admin Bookstore customer Users Roles Permissions Books/write Books/search Isbns/read Isbns/write Books/read Admin Search Read

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

V2 V1

Slide 41

Slide 41 text

Enforce your versioning with scopes

Slide 42

Slide 42 text

We may have authorization policies update breaking changes D ’ y To sum up BookAdmin_V1

Slide 43

Slide 43 text

Wrap up

Slide 44

Slide 44 text

For your next APIs Avoid it first Identify breaking changes Work on the modularity Observe! Consider the big picture Communicate!

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

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