1 of 38

Death By a Thousand API Versions

​

Stanislav Zmiev

2 of 38

API-First

  • A buzzword?
  • A development practice?
  • A design paradigm?

2

3 of 38

It all comes back to Stripe

*Note that I am not associated with Stripe and am only using the publicly available information

3

4 of 38

It all comes back to Stripe

*Note that I am not associated with Stripe and am only using the publicly available information

4

5 of 38

API-First

5

6 of 38

API-First

6

7 of 38

API-First

7

8 of 38

Let’s make an API!

8

9 of 38

What about multiple addresses?

9

10 of 38

What about multiple addresses?

  1. Extend it!

10

11 of 38

What about multiple addresses?

  1. Extend it!
  1. Talk to clients!

11

12 of 38

What about multiple addresses?

  1. Extend it!
  1. Talk to clients!
  1. GraphQL!

12

13 of 38

What about multiple addresses?

  1. Extend it!
  1. Talk to clients!
  1. GraphQL!

13

14 of 38

What about multiple addresses?

  1. Extend it!
  1. Talk to clients!
  1. GraphQL!

14

15 of 38

What about multiple addresses?

  1. Extend it!
  1. Talk to clients!
  1. GraphQL!
  1. API Versioning

15

16 of 38

Okay, so how do we version?

  1. Only one dimension

​

1.2.3-beta

16

17 of 38

Okay, so how do we version?

  1. Only one dimension

​

​

  1. ISO Dates for versions

1.2.3-beta

2022-11-16

17

18 of 38

Okay, so how do we version?

  1. Only one dimension

​

​

  1. ISO Dates for versions

​

​

  1. Versions passed�through a custom header

1.2.3-beta

2022-11-16

Monite-Version: 2022-11-16

18

19 of 38

Wait, but how do we actually version?

19

20 of 38

How solutions are categorized

20

Isolation of old versions from new bugs

Simplicity of implementation and learning

Ease of maintenance

21 of 38

Solution 0: GraphQL

21

Isolation

Simplicity

Ease of Maintenance

22 of 38

Solution 1: Load balancing

22

Isolation

Simplicity

Ease of Maintenance

23 of 38

Solution 2: Single-deployment full app duplication

23

Isolation

Simplicity

Ease of Maintenance

24 of 38

Solution 3: Single-app route duplication

24

Isolation

Simplicity

Ease of Maintenance

25 of 38

Solution 4: Conversion layer

25

Isolation

Simplicity

Ease of Maintenance

26 of 38

But we needed something even more scalable

26

27 of 38

What else can we do?

27

Isolation of old versions from new bugs

Simplicity of implementation and learning

Ease of maintenance

28 of 38

What else can we do?

28

Isolation of old versions from new bugs

Simplicity of implementation and learning

Ease of maintenance

Improved by automated testing

29 of 38

What else can we do?

29

Isolation of old versions from new bugs

Simplicity of implementation and learning

Ease of maintenance

Improved by automated testing

Improved by longer onboarding for new hires

30 of 38

What else can we do?

30

Isolation of old versions from new bugs

Simplicity of implementation and learning

Ease of maintenance

Improved by automated testing

Improved by longer onboarding for new hires

Improved by hiring more people

31 of 38

Let’s get back to the basics

31

Databases have versions

Repositories have versions

32 of 38

Solution 5: Migration-based versioning

32

twitter.com/brandur

Isolation

Simplicity

Ease of Maintenance

33 of 38

Solution 5: Migration-based versioning

33

Isolation

Simplicity

Ease of Maintenance

34 of 38

Cadwyn Version Changes

​

34

35 of 38

Cadwyn versions

35

36 of 38

Cadwyn is not only about FastAPI!

36

37 of 38

So what do you choose?

  • How acceptable is it to introduce a bug into an old version?
  • How often do you make breaking changes?
  • How long do you support your versions?

37

Less

More

Migrate requests and responses like Cadwyn and Stripe

Copy single routes and small pieces of business logic

Deploy versions separately

38 of 38

Thank you!

38

zmievsa@gmail.com

t.me/zmievsa

github.com/zmievsa

twitter.com/zmievsa

linkedin.com/in/zmievsa