API Versioning for Zero Downtime | Devoxx Belgium 2017

API Versioning for Zero Downtime
Patrice Krakow | ING | Lead Architect | APIs
Devoxx Belgium 2017
Antwerp | 2017, November 8 (3.10.0)

PSD2
Payment Services Directive 2015/2366
source: https://ec.europa.eu/info/law/payment-services-psd-2-directive-eu-
2015-2366_en
5
Why API?

We want to be a tech company with
a banking license!
Ralph Hamers, CEO and chairman Executive Board ING Group
source: https://www.ing.com/Newsroom/All-news/We-want-to-be-a-tech-company-with-a-banking-license-Ralph-Hamers.htm

Patrice Krakow
10
Nordic API 2017 | A Journey from API Versioning to Canary Release
https://youtu.be/Yke6Vut2Shc

Patrice Krakow
11
• Sep 2016 – Present
• ING | Lead Architect of the API Platform
• Jul 2012 – Aug 2016
• ING Belgium | SOA Architect
• Jun 2012 – Apr 2013
• Eligible | Co-founder
• Aug 2001 – Jun 2012
• SCA Package (DS Smith) | System Integration Coordinator
…
• Sep 1990 – Jun 1995
• University of Liège | Master of Physics
Nordic API 2017 | A Journey from API Versioning to Canary Release
https://youtu.be/Yke6Vut2Shc

Patrice Krakow
12
• Sep 2016 – Present
• ING | Lead Architect of the API Platform
• Jul 2012 – Aug 2016
• ING Belgium | SOA Architect
• Jun 2012 – Apr 2013
• Eligible | Co-founder
• Aug 2001 – Jun 2012
• SCA Package (DS Smith) | System Integration Coordinator
…
• Sep 1990 – Jun 1995
• University of Liège | Master of Physics
EDIFACT
X12
SGML
CORBA
DCOM
XML
WS
SOA
ESB
REST APIs

Why API Versioning?
13
“Many API designers include versioning information (e.g., numbers in the URL, HTTP headers,
or response body) without much thought about the assumption behind that practice.”
RESTful Web Clients by Mike Amundsen
How?

Why API Versioning?
14
How?
@mamund

Why API Versioning?
15
2nd How?1st Why?

Why API Versioning?
16
2nd How?1st Why?
Versioning = Handling change over time

Why API Versioning?
18
API Consumers API Providers

Why API Versioning?
19
want to change their
APIs as soon as they
have a new brilliant idea

Why API Versioning?
20
want the APIs they are
using to stay stable as long
as they are not interested
by the new brilliant ideas of
the API Providers!

Why API Versioning?
21
What!?
the API Providers!

Why API Versioning?
22
API
Versionin
g
the API Providers!

Why API Versioning?
23
DON’
T
the API Providers!

Meta-Model and Terminology for APIs
26

• API is a set of API endpoints.
• API endpoint is an interface; when using HTTP, an API endpoint is
identified by the triplet {HTTP method, host, URL Path Template}.
• API specification is a precise and comprehensive documentation of the
API endpoints part of the API. We use the OpenAPI/Swagger standard.
• Service is a piece of software, a piece of code, to be run in an out-of-
process component, so it cannot be a library!
• Service version is a version of a service.
• Instance is a running process of a service version. As the running
processes are addressable on TCP/IP network, you can call them via a
socket identified by an IP address and a TCP port.
27
Service
API

28
Service
API

29
API endpoint
Service
API

• API is a set of API endpoints that share a common purpose.
30
API endpoint
Service
API
1
0..n

• API specification is a precise and comprehensive documentation of
the API endpoints part of the API. We use the OpenAPI/Swagger
standard.
31
API endpoint
API specification
Service
API
1
0..n
1
1

standard.
32
API endpoint
API specification
Service
API
1
0..n
1
1
1
1..n

standard.
33
API endpoint
API specification
Service
API
1
0..n
1
1
1
1..n
1

standard.
34
API endpoint
API specification
Service
Service version
API
1
0..n
1
1
1
1..n
1
1
0..n

standard.
35
API endpoint
API specification
Service
Service version
Instance
API
1
0..n
1
1
1
1..n
1
1
0..n
1
0..n

standard.
36
API endpoint
API specification
Service
Service version
Xs.Ys.Zs
Instance
API
1
0..n
1
1
1
1..n
1
1
0..n
1
0..n

standard.
37
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
1
0..n
1
1
1
1..n
1
1
0..n
1
0..n

Semantic Versioning is a de-facto standard way – proposed by Tom Preston-Werner, co-
founder of GitHub – to format version numbers of software packages. You can find the full
specification at http://semver.org/.
Semantic Versioning for both API Specifications and Services
38

MAJOR.MINOR.PATCH or X.Y.Z where X, Y and Z are non-negative integers
1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. PATCH version when you make backwards-compatible bug fixes.
39

Software using Semantic Versioning MUST declare a public API. This API could be declared
in the code itself or exist strictly in documentation. However it is done, it should be precise
and comprehensive.
40

Software using Semantic Versioning MUST declare a public API. This API could be declared
in the code itself or exist strictly in documentation. However it is done, it should be precise
and comprehensive.
Swagger/OpenAPI 2.0 specification – https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
41

10. Patch version Z(a) (x(a).y(a).Z(a) | x(a) > 0) of the Swagger/OpenAPI file MUST be incremented if
changes that do not require any services implementing the API to be changed, are introduced.
11. Patch version Z(s) (x(s).y(s).Z(s) | x(s) > 0) of a service MUST be incremented if only backwards
compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect
behavior and MUST NOT require any changes to the Swagger/OpenAPI file. The patch
version Z(s) of a service MUST NOT be constrained by the patch version Z(a) of the
Swagger/OpenAPI file, and vice-versa.
12. Minor version Y(a) (x(a).Y(a).z(a) | x(a) > 0) of the Swagger/OpenAPI file MUST be incremented if
new, backwards compatible functionality is introduced to the API. It MUST be incremented if
any API functionality is marked as deprecated. It MAY include patch level changes. Patch version
MUST be reset to 0 when minor version is incremented.
13. Minor version Y(s) (x(s).Y(s).z(s) | x(s) > 0) of a service MUST be incremented, together with the
Swagger/OpenAPI file one, if new, backwards compatible functionality is introduced by the API
changes. It MUST NOT be incremented if the minor version of the Swagger/OpenAPI file is not
incremented. It MAY include patch level changes. Patch version MUST be reset to 0 when minor
version is incremented. The minor version Y(s) of a service MUST always be less than or equal
to the minor version Y(a) of the Swagger/OpenAPI file, Y(s) ≤ Y(a).
42

10. Patch version Z(a) (x(a).y(a).Z(a) | x(a) > 0) of the Swagger/OpenAPI file MUST be incremented if
changes that do not require any services implementing the API to be changed, are introduced.
11. Patch version Z(s) (x(s).y(s).Z(s) | x(s) > 0) of a service MUST be incremented if only backwards
compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect
behavior and MUST NOT require any changes to the Swagger/OpenAPI file. The patch
version Z(s) of a service MUST NOT be constrained by the patch version Z(a) of the
Swagger/OpenAPI file, and vice-versa.
12. Minor version Y(a) (x(a).Y(a).z(a) | x(a) > 0) of the Swagger/OpenAPI file MUST be incremented if
new, backwards compatible functionality is introduced to the API. It MUST be incremented if
any API functionality is marked as deprecated. It MAY include patch level changes. Patch version
MUST be reset to 0 when minor version is incremented.
13. Minor version Y(s) (x(s).Y(s).z(s) | x(s) > 0) of a service MUST be incremented, together with the
Swagger/OpenAPI file one, if new, backwards compatible functionality is introduced by the API
changes. It MUST NOT be incremented if the minor version of the Swagger/OpenAPI file is not
incremented. It MAY include patch level changes. Patch version MUST be reset to 0 when minor
version is incremented. The minor version Y(s) of a service MUST always be less than or equal
to the minor version Y(a) of the Swagger/OpenAPI file, Y(s) ≤ Y(a).
43

standard.
44
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
1
0..n
1
1
1
1..n
1
1
0..n
1
0..n

Our Journey to Zero Downtime
45

46
Meta-Model and
Terminology for APIs

47
Meta-Model and
API Gateway

48
Meta-Model and
API Gateway
API Service Discovery

49
Meta-Model and
API Gateway
API Registry

50
Meta-Model and
API Gateway
API Registry

51
Meta-Model and
API Gateway
Routing
API Registry

52
Meta-Model and
API Gateway
Routing
Canary Release
API Registry

53
Meta-Model and
Zero Downtime
API Gateway
Routing
Canary Release
API Registry

54
Meta-Model and
API Gateway
Routing
Canary Release
Zero Downtime
API Registry

API Platform
55
API Gateway
API Registry

API Gateway
59
Outside Inside Office

API Gateway
60

API Gateway
61
API Gateway
on the external edge

API Gateway
62
API Gateway
on the external edge
API Gateway
on the internal edge

API Service Discovery and Client-Side Load Balancing
64

65
API Service
Discovery

66
API Service
Discovery

67
API Service
Discovery
{
"method": "get",
"host": "api.ing.com",
"urlPathTemplate": "/accounts"
}

68
Service~1
API Service
Discovery
{
"method": "get",
}

69
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
{
"method": "get",
}

70
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
{
"method": "get",
}

71

72
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
{
"method": "get",
}

73
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
{
"method": "get",
}

Logical Address Physical Address
{
"method": “get",
"host": “api.ing.com",
"urlPathTemplate": “/accounts"
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
74
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
{
"method": "get",
}

{
"method": "get",
}
75
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
{
"method": "get",
}

{
"method": "get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
76
{
"method": “get",
}
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
77
{
"method": "get",
}
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery

{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
78
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery

{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
79
Instance of
Service~1
10.0.0.1:9001
Instance of
Application~1
API Service
Discovery

Router
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
80
Instance of
Service~1
10.0.0.1:9001
Instance of
Application~1
API Service
Discovery

Router
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
81
Instance of
Service~1
10.0.0.1:9001
Instance of
Application~1
{
"method": “get",
}
API Service
Discovery

Router
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
82
Instance of
Service~1
10.0.0.1:9001
Instance of
Application~1
{
"method": “get",
}
API Service
Discovery

Router
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
83
Instance of
Service~1
10.0.0.1:9001
Instance of
Application~1
{
"method": “get",
}
API Service
Discovery

Router
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
84
Instance of
Service~1
10.0.0.1:9001
Instance of
Application~1
{
"method": “get",
}
API Service
Discovery

Router
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
85
Instance of
Service~1
10.0.0.1:9001
Instance of
Application~1
API Service
Discovery

Router
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
86
Instance of
Service~1
10.0.0.1:9001
Instance of
Application~1
Instance of
Service~1
10.0.0.2:9001
API Service
Discovery
{
"method": “get",
}

{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.2:9001",
}
87
Router
Instance of
Service~1
Instance of
Service~1
10.0.0.1:9001
10.0.0.2:9001
Instance of
Application~1
API Service
Discovery
{
"method": “get",
}

{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.2:9001",
}
88
Router
Instance of
Service~1
Instance of
Service~1
10.0.0.1:9001
10.0.0.2:9001
Instance of
Application~1
API Service
Discovery

{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.2:9001",
}
89
Router
Instance of
Service~1
10.0.0.2:9001
Instance of
Application~1
{
"method": “get",
}
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001

{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.2:9001",
}
90
Router
Instance of
Service~1
10.0.0.2:9001
Instance of
Application~1
{
"method": “get",
}
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001

{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.2:9001",
}
91
Router
Instance of
Service~1
10.0.0.2:9001
Instance of
Application~1
{
"method": “get",
}
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001

{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.2:9001",
}
92
Router
Instance of
Service~1
10.0.0.2:9001
Instance of
Application~1
{
"method": “get",
}
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.2:9001",
}
93
Router
Instance of
Service~1
10.0.0.2:9001
Instance of
Application~1
{
"method": “get",
}
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.2:9001",
}
94

95
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.2:9001",
}

96
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.2:9001",
}

97
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.2:9001",
}

98
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.2:9001",
}

99
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.2:9001",
}

100
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.2:9001",
}

101
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.2:9001",
}

102
Why not
DNS?

103

104

standard.
105
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
1
0..n
1
1
1
1..n
1
1
0..n
1
0..n

standard.
106
API endpoint
Service
1
1..n
API
1
0..n
1

{
"method": "get",
"urlPathTemplate": "/payments"
}
107

{
"method": "post",
}
{
"method": "get",
}
108

109
Service~2
Service~1
{
"method": "post",
}
{
"method": "get",
}

110
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
{
"method": "post",
}
{
"method": "get",
}

111
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
{
"method": "post",
}
{
"method": "get",
}
{
"method": “get",
}
{
"method": “get",
"host": “10.0.0.1:9001",
}
API Service
Discovery

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
112
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
{
"method": "post",
}
{
"method": "get",
}
API Service
Discovery

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
113
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
{
"method": "post",
}
{
"method": "get",
}
API Service
Discovery

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
114
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
115
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
116
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
{
"method": "get",
"urlPathTemplate": “/payments"
}

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
117
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
{
"method": "get",
}

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
118
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
{
"method": "get",
}

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
119
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
{
"method": "get",
}

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
120
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
{
"method": "get",
}

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
121
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
{
"method": "post",
}

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
122
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
{
"method": "post",
}

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
123
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
{
"method": "post",
}

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
124
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
{
"method": "post",
}

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
125
Instance of
Service~2
10.0.0.2:9001
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1

{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
126

127
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
"urlPathTemplate": "/payment"
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}

128
{
"method": "get",
}
{
"method": "get",
"host": "10.0.0.1:9001",
"urlPathTemplate": "/payment"
}
{
"method": "post",
}
{
"method": "post",
"host": "10.0.0.2:9001",
}
DNS

129

130

133

134

In particular, [Baker Street] creates a simpler management model: there is a 1:1 mapping
between a microservice instance and local load balancer (no central load balancer required!),
which means every microservice can be configured and set up in exactly the same way using
a default configuration that works for most services. In addition, the distributed architecture
exhibits linear scale: each new microservice instance adds new load balancing capacity.
Thus, the system is self-provisioning and automatically provides the capacity needed to
handle the available instances of a service. Finally, by storing availability information locally
with each load balancer instance, [Baker Street] ensures that all active microservice
instances can still route traffic, even if some instances of the microservice or instances of
[Baker Street] components.
Source: https://thenewstack.io/baker-street-avoiding-bottlenecks-with-a-client-side-load-balancer-for-microservices/
135

API Registry
138
{
"method": "get",
}

API Registry
139
{
"method": "get",
}

API Registry
140
{
"method": "get",
}

API Registry
141
{
"method": "get",
}
Swagger 2.0

API Registry
142
{
"method": "get",
}
Swagger 2.0

API Registry
143
{
"method": "get",
}
Swagger 2.0
OpenAPI/Swagger 2.0

DON’T write “micro service”, but “microservice”!
144

DON’T mix “Open API” and “OpenAPI”!
145

API Registry
146
{
"method": "get",
}
Swagger 2.0
OpenAPI/Swagger 2.0

API Registry
147
{
"method": "get",
}
Swagger 2.0
OpenAPI/Swagger 2.0  OpenAPI 3.0

API Registry
148
{
"method": "get",
}
Swagger 2.0
OpenAPI/Swagger 2.0
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

API Registry
149
{
"method": "get",
}
swagger: '2.0'
info:
title: Account Information API
version: 1.0.1
host: api.ing.com
basePath: /
schemes:
- https
consumes:
- application/json
produces:
- application/json
paths:
/accounts:
get:
parameters:
- ...

API Registry
150
{
"method": "get",
}
swagger: '2.0'
info:
version: 1.0.1
host: api.ing.com
basePath: /
schemes:
- https
consumes:
- application/json
produces:
- application/json
paths:
/accounts:
get:
parameters:
- ...
API Registry

API Registry
151
Router
Instance of
Service~1
10.0.0.1:9001
Instance of
Application~1
API Service
Discovery
API Registry

API Registry
152
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
API Registry

API Registry
153
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
API Registry

API Registry
154
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
API Provider
API Registry

API Registry
155
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
API ProviderAPI Consumer
API Registry

API Registry
156
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
API Registry

API Registry
157
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
Is this service
allowed to implement
this API endpoint?
API Registry

API Registry
158
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
Is this service
allowed to implement
this API endpoint?
Is this application
allowed to call
this API endpoint?
API Registry

API Registry
159
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
Manifest
Is this application
allowed to call
this API endpoint?
API Registry

API Registry
160
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
Manifest
Subscription
API Registry

API Registry
161
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
Manifest
(Subscription)
Peer-Token
API Registry

Within our organization, we want to control which service is
implementing which part of an API.
The Manifest
162
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API

We can implement this control by creating a structure
making an explicit link between a service and a list of API
endpoints part of an API. We will call such a structure
our manifest.
The Manifest
163
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
Manifest

We can implement this control by creating a structure
making an explicit link between a service and a list of API
endpoints part of an API. We will call such a structure
our manifest.
When we generate a manifest, we store/remember the
version of the API specification that documents API
endpoint at the moment the manifest is generated.
The Manifest
164
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
Manifest

{
"serviceName": "<Name of the Service>",
"endpoints": [
{
"method": "<paths/{path}/get|post|put|patch|delete from Swagger/OpenAPI>",
"host": "<host from Swagger/OpenAPI>",
"urlPathTemplate": "<paths/{path} from Swagger/OpenAPI>",
"apiSpecificationVersion": "<info/version from Swagger/OpenAPI>"
},
...
]
}
The Manifest
165

{
"serviceName": "<Name of the Service>",
"endpoints": [
{
},
...
]
}
The Manifest
166
Service~1
{
"method": "get",
}

{
"serviceName": "Service~1",
"endpoints": [
{
"method": "get",
"urlPathTemplate": "/accounts",
"apiSpecificationVersion": “1.0.1"
},
...
]
}
The Manifest
167
Service~1
{
"method": "get",
}
swagger: '2.0'
info:
version: 1.0.1
host: api.ing.com
basePath: /
schemes:
- https
consumes:
- application/json
produces:
- application/json
paths:
/accounts:
get:
parameters:
- ...

Subscription and Peer-Token
168

When a software package wants to call
an API endpoint, it has first to declare its
intention to do so.
169
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API

intention to do so.
We call subscription this relation
between the software package, called an
application, and a specific API
endpoint.
170
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
SubscriptionApplication

171

intention to do so.
We call subscription this relation
between the software package, called an
application, and a specific API
endpoint.
When we generate a peer-token, we
store/remember the version of the API
specification that documents the API
endpoint at the moment the
subscription is created.
172
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
(Subscription)
Peer-Token
Application

{
“applicationName": "<Name of the Application>",
"endpoints": [
{
},
...
]
}
173

{
“applicationName": "<Name of the Application>",
"endpoints": [
{
},
...
]
}
174
This is the exact same structure as the manifest ;-)

175

{
"applicationName": "Application~1",
"endpoints": [
{
"method": "get",
"apiSpecificationVersion": "1.0.1"
},
...
]
}
176

API Platform
177
API Gateway
API Registry

API Platform
179
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1

API Platform
180
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry

API Platform
181
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal

API Platform
183
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal

API Platform
184
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Service~1

API Platform
185
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Service~1
Manifest
Manifest

API Platform
186
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Service~1
Manifest
Manifest

API Platform
187
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Service~1
Manifest
Manifest
Service version
Xs.Ys.Zs
1
0..n

API Platform
188
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Service~1
Manifest
Manifest
Service version
Xs.Ys.Zs
1
0..n
API Provider

API Platform
189
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Manifest
Manifest
Service version
Xs.Ys.Zs
1
0..n
API Provider
Instance
1
0..n
Instance of
Service~1
10.0.0.1:9001

API Platform
190
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Manifest
Manifest
Service version
Xs.Ys.Zs
1
0..n
API Provider
Instance
1
0..n
Instance of
Service~1
10.0.0.1:9001

API Platform
191
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Manifest
Manifest
Service version
Xs.Ys.Zs
1
0..n
API Provider
Instance
1
0..n
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery

API Platform
192
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Manifest
Manifest
Service version
Xs.Ys.Zs
1
0..n
API Provider
Instance
1
0..n
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
API Consumer

API Platform
193
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Manifest
Manifest
Service version
Xs.Ys.Zs
1
0..n
API Provider
Instance
1
0..n
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
API Consumer

API Platform
194
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Manifest
Manifest
Service version
Xs.Ys.Zs
1
0..n
API Provider
Instance
1
0..n
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
API Consumer
Peer-Token
(Subscription)
Peer-Token
Application

API Platform
195
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Manifest
Manifest
Service version
Xs.Ys.Zs
1
0..n
API Provider
Instance
1
0..n
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Router
Instance of
Application~1
API Consumer
Peer-Token
(Subscription)
Peer-Token
Application

Router
API Platform
196
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Manifest
Manifest
Service version
Xs.Ys.Zs
1
0..n
API Provider
Instance
1
0..n
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
API Consumer
Peer-Token
(Subscription)
Peer-Token
Application
API SDK

Router
API Platform
197
API endpoint
API specification
Xa.Ya.Za
API
1
0..n
1
1
API Registry
API Developer
Portal
Service
1
1..n
Manifest
Manifest
Service version
Xs.Ys.Zs
1
0..n
API Provider
Instance
1
0..n
Instance of
Service~1
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
API Consumer
Peer-Token
(Subscription)
Peer-Token
Application
API SDK SDK

API Platform
198
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
1
0..n
1
1
1
1..n
1
1
0..n
1
0..n
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
API Registry
API Developer
Portal
API SDK SDK
Peer-Token
Manifest
(Subscription)
Peer-Token
Application
Manifest

Routing Conjecture
200
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
1
0..n
1
1
1
1..n
1
1
0..n
1
0..n
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
API Registry
API Developer
Portal
API SDK SDK
Peer-Token
Manifest
(Subscription)
Peer-Token
Application
Manifest

Routing Conjecture
201
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
1
0..n
1
1
1
1..n
1
1
0..n
1
0..n
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
API Registry
API Developer
Portal
API SDK SDK
Peer-Token
Manifest
(Subscription)
Peer-Token
Application
Manifest

Routing Conjecture
202
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
1
0..n
1
1
1
1..n
1
1
0..n
1
0..n
Router
Instance of
Application~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
API Registry
API Developer
Portal
API SDK SDK
Peer-Token
Manifest
(Subscription)
Peer-Token
Application
Manifest

The canary release is a technique to reduce the risk of introducing a new software version in
production by slowly rolling out the change to a small subset of users before making it
available to everybody.
Canary Release
203

The canary release is a technique to reduce the risk of introducing a new software version in
production by slowly rolling out the change to a small subset of users before making it
available to everybody.
The name for this technique originates from miners who would carry a canary in a cage down
the coal mines. If toxic gases leaked into the mine, it would kill the canary before killing the
miners.
A canary release provides a similar form
of early warning for potential problems
before impacting your user base.
Canary Release
204
Source: https://martinfowler.com/bliki/CanaryRelease.html

Canary Release
205
Application~1 Router
Instance of
Service~1 v1.0.0

Canary Release
206
Instance of
Service~1 v1.1.0
Instance of
Service~1 v1.0.0

Canary Release
207
Instance of
Service~1 v1.1.0
Instance of
Service~1 v1.0.0
100%
10%
90%

Canary Release
208
Instance of
Service~1 v1.1.0
Instance of
Service~1 v1.0.0
100%
50%
50%

Canary Release
209
Instance of
Service~1 v1.1.0
Instance of
Service~1 v1.0.0
100%
90%
10%

Canary Release
210
Instance of
Service~1 v1.1.0
Instance of
Service~1 v1.0.0
100%
100%

We can now implement the Canary Release, but let’s be careful
Application (API Specification x.Y.z)  (Yes)API endpoint (API Specification x.Y.z)
Application (API Specification x.Y.z)  (Yes)API endpoint (API Specification x.Y+1.z)
Application (API Specification x.Y+1.z)  (Yes)API endpoint (API Specification x.Y+1.z)
Application (API Specification x.Y+1.z)  (No) API endpoint (API Specification x.Y.z)
But, we can handle that by building the routing rules with information form both
the API Registry and the API Service Discovery ;-)
Routing
211

1. Application (API Specification x.Y.z)  (Yes)service (API Specification x.Y.z)
Application (API Specification x.Y.z)  (Yes)API endpoint (API Specification x.Y+1.z)
Routing
212

2. Application (API Specification x.Y.z)  (Yes)service (API Specification x.Y+1.z)
Routing
213

3. Application (API Specification x.Y+1.z)  (Yes)service (API Specification x.Y+1.z)
Routing
214

4. Application (API Specification x.Y+1.z)  (No) service (API Specification x.Y.z)
Routing
215

Routing
216

But, we can handle that by building the routing rules with information from both
API Registry and API Service Discovery ;-)
Routing
217

Routing
219
{
"method": "get",
}

Routing
220
{
"method": "get",
}
v1.0.3

Routing
221
swagger: '2.0'
info:
version: 1.0.3
host: api.ing.com
basePath: /
schemes:
- https
paths:
/accounts:
get:
parameters:
- ...
{
"method": "get",
}
v1.0.3

Routing
222
API Registry
swagger: '2.0'
info:
version: 1.0.3
host: api.ing.com
basePath: /
schemes:
- https
paths:
/accounts:
get:
parameters:
- ...
{
"method": "get",
}
v1.0.3

Routing
223
API Registry
API Developer
Portal
swagger: '2.0'
info:
version: 1.0.3
host: api.ing.com
basePath: /
schemes:
- https
paths:
/accounts:
get:
parameters:
- ...
{
"method": "get",
}
v1.0.3

Routing
224
API Registry
API Developer
Portal
v1.0.3
swagger: '2.0'
info:
version: 1.0.3
host: api.ing.com
basePath: /
schemes:
- https
paths:
/accounts:
get:
parameters:
- ...

Routing
225
API Registry
API Developer
Portal
Service~1v1.0.3
swagger: '2.0'
info:
version: 1.0.3
host: api.ing.com
basePath: /
schemes:
- https
paths:
/accounts:
get:
parameters:
- ...

Routing
226
v1.0.3
API Registry
API Developer
Portal
Service~1
Manifest
{
"endpoints": [
{
"method": "get",
}
]
}
swagger: '2.0'
info:
version: 1.0.3
host: api.ing.com
basePath: /
schemes:
- https
paths:
/accounts:
get:
parameters:
- ...

Routing
227
v1.0.3
API Registry
API Developer
Portal
Service~1
Manifest
{
"endpoints": [
{
"method": "get",
}
]
}

Routing
228
v1.0.3
API Registry
API Developer
Portal
Service~1
Manifest
{
"endpoints": [
{
"method": "get",
}
]
}

Routing
229
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
{
"serviceName": “Service~1",
"endpoints": [
{
"method": "get",
}
]
}

Routing
230
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
{
"endpoints": [
{
"method": "get",
}
]
}

Routing
231
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
{
"endpoints": [
{
"method": "get",
}
]
}
10.0.0.1:9001
API Service
Discovery

Routing
232
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
{
"endpoints": [
{
"method": "get",
}
]
}
10.0.0.1:9001
API Service
Discovery
{
"ip": "10.0.0.1:9001",
"port": "9001"
}

Routing
233
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
{
"endpoints": [
{
"method": "get",
}
]
}
10.0.0.1:9001
API Service
Discovery
{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}

Routing
234
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}

{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}
Routing
235
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery

{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}
Routing
236
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery

{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}
Routing
237
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Application~1

{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}
Routing
238
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Application~1
(when v1.0.3)
Subscription

{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}
Routing
239
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Application~1
(when v1.0.3)
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "get",
}
]
}

{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}
Routing
240
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}

Router
{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}
Routing
241
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK

Router
{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}
Routing
242
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token

Router
{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}
Routing
243
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token

Router
{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"endpoints": [
{
"method": "get",
}
]
}
}
Routing
244
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
}
]

Router
Routing
245
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
}
]

Router
Routing
246
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
}
]

Router
Routing
247
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
}
]
v1.1.0

Router
Routing
248
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
}
]
v1.1.0 Service~1 v1.1.2
10.0.0.2:9001

Router
Routing
249
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
}
]
v1.1.0 Service~1 v1.1.2
10.0.0.2:9001
Manifest

Router
Routing
250
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
}
]
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest

Router
Routing
251
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
}
]
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest

Router
Routing
252
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
},
{
"ip": "10.0.0.2",
"port": "9001",
},
]
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest

Router
Routing
253
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
Instance of
Application~1
(when v1.0.3)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
API SDK
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
},
{
"ip": "10.0.0.1",
"port": "9001",
},
]
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest

Routing
254
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
API SDK
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest

Router
Routing
255
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
API SDK
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest
Application~2

Router
Routing
256
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
API SDK
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest
Application~2
(when v1.1.0)
Subscription

Router
Routing
257
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
API SDK
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest
Application~2
(when v1.1.0)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}

Router
Routing
258
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
API SDK
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest
Instance of
Application~2
(when v1.1.0)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}

Router
Routing
259
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
API SDK
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest
Instance of
Application~2
(when v1.1.0)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
Peer-Token

Router
Routing
260
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
API SDK
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest
Instance of
Application~2
(when v1.1.0)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
},
{
"ip": "10.0.0.2",
"port": "9001",
},
]

Router
Routing
261
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
API SDK
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest
Instance of
Application~2
(when v1.1.0)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
Peer-Token
[
{
"ip": "10.0.0.1",
"port": "9001",
},
{
"ip": "10.0.0.2",
"port": “9001",
},
]

Router
Routing
262
v1.0.3
API Registry
API Developer
Portal
Instance of
Service~1 v1.0.5
Manifest
10.0.0.1:9001
API Service
Discovery
API SDK
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Manifest
Instance of
Application~2
(when v1.1.0)
Subscription
{
"endpoints": [
{
"method": "get",
}
]
}
Peer-Token
[
{
"ip": “10.0.0.1",
"port": "9001",
},
{
"ip": “10.0.0.2",
"port": “9001",
},
]

• Make an explicit distinction between API (endpoints) and services
Summary
264

Summary
265

• Use semantic versioning for both API specifications (OpenAPI/Swagger) and services
Summary
266

• Make an explicit link between service and API endpoints within a manifest*
Summary
267

• Register instances at run-time to API Service Discovery
• Get the physical address of instances at run-time via API Service Discovery
Summary
268

• Request explicit subscriptions to API endpoints at design-time, and store them in API
Registry
• Make subscriptions available at run-time with peer-tokens*
Summary
269

Registry
• Let the (client-side) router make a wise decision about which instance to call by combining
information coming from API Registry and API Service Discovery
* The structure of a manifest and a peer-token is the same – I like symmetry ;-) – and, for
both, the trick is to remember/store the version of API specification ;-)
Summary
270

Registry
Summary
271

Registry
• Extend this technique to other strategies for Canary Release, Confidence Check, A/B testing,
… it’s a unified way to handle any special routing mechanisms you want to implement ;-)
Summary
272

• Make an explicit distinction between the interface and the code
Summary
273
Click to edit Master title style

• Make an explicit distinction between the interface and the code
Summary
274
Click to edit Master title style

API Versioning, DON’T bother your
consumers with it ;-)
Thank You!
Patrice Krakow, Lead Architect, APIs, ING
https://www.linkedin.com/in/patricekrakow/
@patricekrakow

API Versioning for Zero Downtime | Devoxx Belgium 2017

More Related Content

What's hot (18)

Similar to API Versioning for Zero Downtime | Devoxx Belgium 2017 (20)

Recently uploaded (20)

API Versioning for Zero Downtime | Devoxx Belgium 2017

Editor's Notes