1
00:00:00,110 --> 00:00:01,880
Welcome to the architecture 
corner. 

2
00:00:02,270 --> 00:00:05,280
You know, there's this massive 
paradox in software development.

3
00:00:05,390 --> 00:00:08,720
The more successful your API 
becomes like, the harder it is 

4
00:00:08,730 --> 00:00:11,080
to actually update it without 
breaking everyone's app. 

5
00:00:11,170 --> 00:00:14,260
You finally get thousands of 
users depending on your service,

6
00:00:14,310 --> 00:00:17,460
and suddenly you're just 
completely paralyzed by the fear

7
00:00:17,470 --> 00:00:20,960
of breaking their integrations. 
Yeah, it is the ultimate trap of

8
00:00:20,970 --> 00:00:23,600
success. 
So to get out of it, our mission

9
00:00:23,610 --> 00:00:27,800
today is extracting some really 
solid strategies from a guide by

10
00:00:27,810 --> 00:00:32,540
author Mario Bittencourt on how 
to evolve APIs painlessly. 

11
00:00:32,770 --> 00:00:36,580
We're figuring out how you 
balance that aggressive progress

12
00:00:36,650 --> 00:00:39,700
with rock solid stability. 
Right, so to understand how to 

13
00:00:39,710 --> 00:00:42,730
successfully upgrade an API, we 
probably first need to define 

14
00:00:42,740 --> 00:00:45,460
what will actually doesn't break
it. 

15
00:00:45,510 --> 00:00:48,880
Like where is the line between a
safe tweak and a total disaster?

16
00:00:48,990 --> 00:00:51,740
True backward compatibility is 
strictly additive. 

17
00:00:51,790 --> 00:00:55,160
You're safe if you are just 
adding things, I mean adding new

18
00:00:55,170 --> 00:00:58,890
resources, optional request 
parameters or extra properties 

19
00:00:58,900 --> 00:01:00,320
to a. 
Response because the consuming 

20
00:01:00,330 --> 00:01:02,810
application just nor is that new
data if it doesn't need it, 

21
00:01:02,820 --> 00:01:04,300
right? 
Exactly. 

22
00:01:04,349 --> 00:01:09,360
The moment you change existing 
behavior or modify the shape of 

23
00:01:09,370 --> 00:01:13,360
an expected response, you force 
a major version of a date. 

24
00:01:13,370 --> 00:01:15,020
It's a lot like a board game 
actually. 

25
00:01:15,090 --> 00:01:17,700
Releasing an optional expansion 
pack is totally fine. 

26
00:01:17,710 --> 00:01:19,920
Players can use the new cards or
just ignore them. 

27
00:01:20,050 --> 00:01:23,200
But if you change the core rules
of the base game, you ruin the 

28
00:01:23,210 --> 00:01:25,500
experience for everyone 
currently playing. 

29
00:01:25,570 --> 00:01:27,820
You can't just swap out the 
board while the pieces are still

30
00:01:27,830 --> 00:01:29,920
on it. 
That is a great analogy. 

31
00:01:30,030 --> 00:01:33,060
That's the exact friction. 
But you know, eventually the 

32
00:01:33,070 --> 00:01:36,960
core rules just must change to 
accommodate new business logic. 

33
00:01:37,030 --> 00:01:38,580
You have to launch your version 
too. 

34
00:01:38,630 --> 00:01:40,480
But from the clients 
perspective, I mean upgrading 

35
00:01:40,490 --> 00:01:43,310
code is a pure financial and 
time cost. 

36
00:01:43,550 --> 00:01:45,640
They aren't upgrading their 
integration for fun. 

37
00:01:45,730 --> 00:01:49,140
Why would they ever prioritize 
moving to V2 when V1 works 

38
00:01:49,150 --> 00:01:50,390
perfectly fine for them? 
Right. 

39
00:01:50,400 --> 00:01:53,420
So maintainers really have to 
reframe that upgrade from a 

40
00:01:53,430 --> 00:01:57,200
chore into an investment. 
You do that by communicating the

41
00:01:57,210 --> 00:02:00,360
concrete business benefits 
early, especially if like 

42
00:02:00,370 --> 00:02:02,710
external architectural changes 
are driving the. 

43
00:02:02,720 --> 00:02:05,210
Update OK, but communication 
only gets you so far. 

44
00:02:05,260 --> 00:02:08,910
True, which is why the real key 
is providing A frictionless 

45
00:02:08,960 --> 00:02:12,230
migration path and we're 
actually seeing maintainers 

46
00:02:12,240 --> 00:02:15,650
provide AI driven tooling to 
automate the transition. 

47
00:02:15,660 --> 00:02:17,310
OK wait, I have to push back 
there. 

48
00:02:17,620 --> 00:02:21,630
AI is notoriously prone to 
hallucinations if I'm a client 

49
00:02:21,640 --> 00:02:24,570
handling secure data. 
I'm definitely not trusting a 

50
00:02:24,580 --> 00:02:27,990
generic LM to rewrite my 
critical infrastructure just to 

51
00:02:28,000 --> 00:02:31,250
match your new API. 
Oh, I completely agree, but you 

52
00:02:31,260 --> 00:02:34,200
wouldn't use a generic prompt. 
The strategy here is for the 

53
00:02:34,210 --> 00:02:38,240
maintainer to package a specific
AI skill loaded with 

54
00:02:38,250 --> 00:02:41,480
deterministic migration recipes.
Oh, so they aren't just 

55
00:02:41,490 --> 00:02:42,480
guessing? 
Exactly. 

56
00:02:42,490 --> 00:02:45,280
Instead of the AI guessing how 
the new API works, the 

57
00:02:45,290 --> 00:02:47,860
maintainer provides the exact 
mapping logic. 

58
00:02:47,930 --> 00:02:50,860
So the client's AI agent simply 
executes those predefined 

59
00:02:50,870 --> 00:02:52,920
recipes against their local code
base. 

60
00:02:52,970 --> 00:02:56,940
It translates the V1 calls to V2
automatically and safely OK. 

61
00:02:56,950 --> 00:02:59,720
I see, but even with automated 
recipes, large enterprise 

62
00:02:59,730 --> 00:03:02,180
clients take months to migrate. 
You are going to be stuck 

63
00:03:02,190 --> 00:03:04,250
maintaining V1 and V2 
simultaneously. 

64
00:03:04,260 --> 00:03:06,460
How do you pull that off 
without, you know, duplicating 

65
00:03:06,470 --> 00:03:09,130
your code base and maintaining 
parallel universes? 

66
00:03:09,200 --> 00:03:12,770
Yeah, the traditional method is 
branching your code, literally 

67
00:03:12,780 --> 00:03:16,370
forking it into a V1 path and a 
V2 path, but that becomes a 

68
00:03:16,380 --> 00:03:17,550
complete maintenance. 
Nightmare. 

69
00:03:17,560 --> 00:03:20,840
So what is the better option? 
The superior strategy, and this 

70
00:03:20,850 --> 00:03:23,970
is used heavily by companies 
like Stripe, is the adapter 

71
00:03:23,980 --> 00:03:26,170
pattern. 
You basically isolate all the 

72
00:03:26,180 --> 00:03:29,750
version changes right at the 
APIs edge, far away from your 

73
00:03:29,760 --> 00:03:32,030
core logic. 
Let's use the To Do app from the

74
00:03:32,040 --> 00:03:35,300
source material To ground this, 
say V one of your app uses a 

75
00:03:35,310 --> 00:03:39,600
simple true or false completed 
status for a task, but V2 gets 

76
00:03:39,610 --> 00:03:42,880
more sophisticated, swapping 
that out for a detailed status 

77
00:03:42,890 --> 00:03:46,360
list like in Progress or Done 
and adding a new due date 

78
00:03:46,370 --> 00:03:48,390
property. 
Right, so the mechanics of the 

79
00:03:48,400 --> 00:03:51,840
adapter pattern handle that 
discrepancy seamlessly when a 

80
00:03:51,850 --> 00:03:55,240
legacy V1 request comes in and 
edge adapter intercepts it 

81
00:03:55,250 --> 00:03:57,080
before it ever touches your core
application. 

82
00:03:57,090 --> 00:03:58,700
So basically catches it at the 
door. 

83
00:03:58,710 --> 00:04:00,720
Exactly. 
It outcasts that request. 

84
00:04:00,790 --> 00:04:03,860
It takes that simple true or 
false boolean and translates it 

85
00:04:03,870 --> 00:04:07,800
into the new 32 status format. 
It fills in a default value for 

86
00:04:07,810 --> 00:04:10,740
the missing due date and then 
passes that standardized modern 

87
00:04:10,750 --> 00:04:12,780
request to your shared core 
engine. 

88
00:04:12,930 --> 00:04:15,720
Meaning your core engine only 
ever speaks V2. 

89
00:04:15,810 --> 00:04:18,720
You got it? 
Yeah, it processes the V2 data, 

90
00:04:18,790 --> 00:04:21,579
generates a V2 response, and 
sends it back out. 

91
00:04:22,050 --> 00:04:24,990
Then a second adapter catches 
that outbound response and 

92
00:04:25,000 --> 00:04:27,760
strips it back down to the old 
V1 shape before it reaches the 

93
00:04:27,770 --> 00:04:29,800
client. 
Wow, so your core application 

94
00:04:29,810 --> 00:04:33,060
remains completely pristine and 
never even knows V1 exists? 

95
00:04:33,070 --> 00:04:35,520
Exactly. 
It fundamentally changes how you

96
00:04:35,530 --> 00:04:38,610
manage technical debt. 
You stop letting old versions 

97
00:04:38,620 --> 00:04:40,290
dictate your future 
architecture. 

98
00:04:40,360 --> 00:04:43,150
That makes a lot of sense, O 
When you're building your own 

99
00:04:43,160 --> 00:04:46,230
services and planning that next 
big feature, ask yourself, are 

100
00:04:46,240 --> 00:04:49,570
you duplicating code branches 
and polluting your core logic, 

101
00:04:49,620 --> 00:04:53,050
or are you efficiently isolating
legacy requests at the edge? 

102
00:04:53,320 --> 00:04:55,390
It is definitely something you 
have to actively design. 

103
00:04:55,400 --> 00:04:57,990
For absolutely, and I want to 
leave you with a final thought 

104
00:04:58,000 --> 00:05:00,960
to Mull over. 
If we are already billing AI 

105
00:05:00,970 --> 00:05:04,050
skills with specific recipes to 
help clients migrate to new 

106
00:05:04,060 --> 00:05:08,180
APIs, how long until our API 
gateways automatically generate 

107
00:05:08,190 --> 00:05:11,490
and deploy these V1V2 adapters 
on the family? 

108
00:05:11,500 --> 00:05:14,390
Oh man, yeah, that would 
completely rewrite how we think 

109
00:05:14,400 --> 00:05:16,130
about versioning. 
Make sure to check the 

110
00:05:16,140 --> 00:05:18,650
description For more information
on everything we discussed 

111
00:05:18,660 --> 00:05:20,710
today. 
And don't forget to subscribe 

112
00:05:20,720 --> 00:05:23,470
for free to the Architecture 
Corner newsletter at 

113
00:05:23,480 --> 00:05:25,860
architecturecorner.substack.com.