Presentation given at APIDays Zurich, the 27th of September 2017, about how an API Versioning guidelines becomes a proposal to unify Canary Release, Confidence Check and A/B testing on APIs.

1. A Journey from API Versioning to
Canary Release
Patrice Krakow | ING | Lead Architect | APIs
APIDays Zurich - API Economy and Microservices
Zurich | 2017, September 27 (1.5.0)

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

3. Patrice Krakow
3
• 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

4. A Journey from API Versioning to Canary Release
4

5. Why?
5

6. API Providers want to change their APIs as soon as they have a new brilliant idea
Why?
6

7. API Providers want to change their APIs as soon as they have a new brilliant idea
vs.
API Consumers 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?
7

8. API Providers want to change their APIs as soon as they have a new brilliant idea
API Consumers 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?
8

9. API Providers want to change their APIs as soon as they have a new brilliant idea
vs.
API Consumers 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?
9

10. API Providers want to change their APIs as soon as they have a new brilliant idea
vs.
API Consumers 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?
10

11. Canary
11

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

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

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

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

16. Canary Release
16
Application~1 Router
Instance of
Service~1 v1.1.0
Instance of
Service~1 v1.0.0
100%
10%
90%

17. Canary Release
17
Application~1 Router
Instance of
Service~1 v1.1.0
Instance of
Service~1 v1.0.0
100%
50%
50%

18. Canary Release
18
Application~1 Router
Instance of
Service~1 v1.1.0
Instance of
Service~1 v1.0.0
100%
90%
10%

19. Canary Release
19
Application~1 Router
Instance of
Service~1 v1.1.0
Instance of
Service~1 v1.0.0
100%
100%

20. Meta-Model and Terminology for APIs
20

21. • 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.
21
Meta-Model and Terminology for APIs
Service
API

22. • 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.
22
Meta-Model and Terminology for APIs
Service
API

23. • 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.
23
Meta-Model and Terminology for APIs
API endpoint
Service
API

24. • API is a set of API endpoints that share a common purpose.
• 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.
24
Meta-Model and Terminology for APIs
API endpoint
Service
API

25. • API is a set of API endpoints that share a common purpose.
• 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.
25
Meta-Model and Terminology for APIs
API endpoint
API specification
Service
API

26. • API is a set of API endpoints that share a common purpose.
• 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.
26
Meta-Model and Terminology for APIs
API endpoint
API specification
Service
API

27. • API is a set of API endpoints that share a common purpose.
• 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
Meta-Model and Terminology for APIs
API endpoint
API specification
Service
Service version
API

28. • API is a set of API endpoints that share a common purpose.
• 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.
28
Meta-Model and Terminology for APIs
API endpoint
API specification
Service
Service version
Instance
API

29. • API is a set of API endpoints that share a common purpose.
• 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.
29
Meta-Model and Terminology for APIs
API endpoint
API specification
Service
Service version
Xs.Ys.Zs
Instance
API

30. • API is a set of API endpoints that share a common purpose.
• 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.
30
Meta-Model and Terminology for APIs
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API

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

32. 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/.
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.
Semantic Versioning for both API Specifications and Services
32

33. 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/.
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.
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.
Semantic Versioning for both API Specifications and Services
33

34. 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/.
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.
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
Semantic Versioning for both API Specifications and Services
34

35. 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).
Semantic Versioning for both API Specifications and Services
35

36. 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).
Semantic Versioning for both API Specifications and Services
36

37. API Gateway
37

38. API Gateway
38
Outside Inside

39. API Gateway
39
Outside Inside

40. API Gateway
40
Outside Inside Office

41. API Gateway
41
Outside Inside Office

42. API Gateway
42
Outside Inside Office
API Gateway
on the external edge

43. API Gateway
43
Outside Inside Office
API Gateway
on the external edge
API Gateway
on the internal edge

44. API Service Discovery and Client-Side Load Balancing
44
API Service
Discovery

45. API Service Discovery and Client-Side Load Balancing
45
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001

46. API Service Discovery and Client-Side Load Balancing
46
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
Application~1

47. API Service Discovery and Client-Side Load Balancing
47
Router
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
Application~1

48. API Service Discovery and Client-Side Load Balancing
48
Router
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
Application~1

49. API Service Discovery and Client-Side Load Balancing
49
Router
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
Application~1

50. API Service Discovery and Client-Side Load Balancing
50
Router
Instance of
Service~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
10.0.0.2:9001
Application~1

51. API Service Discovery and Client-Side Load Balancing
51
Router
Instance of
Service~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
10.0.0.2:9001
Application~1

52. API Service Discovery and Client-Side Load Balancing
52
Router
Instance of
Service~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
10.0.0.2:9001
Application~1

53. API Service Discovery and Client-Side Load Balancing
53

54. API Service Discovery and Client-Side Load Balancing
54

55. 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/
API Service Discovery and Client-Side Load Balancing
55

56. The Manifest
56
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API

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

58. Within our organization, we want to control which service is
implementing which part of an 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
58
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
Manifest

59. Within our organization, we want to control which service is
implementing which part of an 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.
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
59
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
Manifest

60. {
"serviceName": "<Name of the service = client certificate OU>",
"endpoints": [
{
"method": "<paths/{path} of the Swagger/OpenAPI file>",
"host": "<host of the Swagger/OpenAPI file>",
"urlPathTemplate": "<paths of the Swagger/OpenAPI file>",
"apiSpecificationVersion": "<info/version of the Swagger/OpenAPI file>"
},
...
]
}
The Manifest
60

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

62. When a software package wants to call
an API endpoint, it has first to declare its
intention to do so.
We call subscription this relation
between the software package, called an
application, and a specific API
endpoint.
Subscription and Peer Token
62
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
SubscriptionApplication

63. When a software package wants to call
an API endpoint, it has first to declare its
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 approved.
Subscription and Peer Token
63
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
SubscriptionApplication

64. {
"applicationName": "<if application == service = client certificate OU>",
"endpoints": [
{
"method": "<paths/{path} of the Swagger/OpenAPI file>",
"host": "<host of the Swagger/OpenAPI file>",
"urlPathTemplate": "<paths of the Swagger/OpenAPI file>",
"apiSpecificationVersion": "<info/version of the Swagger/OpenAPI file>"
},
...
]
}
Subscription and Peer Token
64

65. {
"applicationName": "<if application == service = client certificate OU>",
"endpoints": [
{
"method": "<paths/{path} of the Swagger/OpenAPI file>",
"host": "<host of the Swagger/OpenAPI file>",
"urlPathTemplate": "<paths of the Swagger/OpenAPI file>",
"apiSpecificationVersion": "<info/version of the Swagger/OpenAPI file>"
},
...
]
}
Subscription and Peer Token
65
This is the exact same structure as the manifest ;-)

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

67. We can now implement the Canary Release, but let’s be careful
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)
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
67

68. We can now implement the Canary Release, but let’s be careful
1. Application (API Specification x.Y.z)  (Yes)service (API Specification x.Y.z)
2. Application (API Specification x.Y.z)  (Yes)service (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
68

69. We can now implement the Canary Release, but let’s be careful
1. Application (API Specification x.Y.z)  (Yes)service (API Specification x.Y.z)
2. Application (API Specification x.Y.z)  (Yes)service (API Specification x.Y+1.z)
3. Application (API Specification x.Y+1.z)  (Yes)service (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
69

70. We can now implement the Canary Release, but let’s be careful
1. Application (API Specification x.Y.z)  (Yes)service (API Specification x.Y.z)
2. Application (API Specification x.Y.z)  (Yes)service (API Specification x.Y+1.z)
3. Application (API Specification x.Y+1.z)  (Yes)service (API Specification x.Y+1.z)
4. Application (API Specification x.Y+1.z)  (No) service (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
70

71. We can now implement the Canary Release, but let’s be careful
1. Application (API Specification x.Y.z)  (Yes)service (API Specification x.Y.z)
2. Application (API Specification x.Y.z)  (Yes)service (API Specification x.Y+1.z)
3. Application (API Specification x.Y+1.z)  (Yes)service (API Specification x.Y+1.z)
4. Application (API Specification x.Y+1.z)  (No) service (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
71

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

73. Routing
73

74. Routing
74
v1.0.3

75. Routing
75
v1.0.3
swagger: '2.0‘
info:
title: My API
version: 1.0.3
...

76. Routing
76
API Registry
v1.0.3
swagger: '2.0‘
info:
title: My API
version: 1.0.3
...

77. Routing
77
API Registry
v1.0.3

78. Routing
78
Service~1
API Registry
v1.0.3

79. Routing
79
Service~1
API Registry
v1.0.3
Manifest

80. Routing
80
Service~1
API Registry
v1.0.3
{
"serviceName": "Service~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
Manifest

81. Routing
81
Service~1
API Registry
v1.0.3
Manifest

82. Routing
82
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest

83. Routing
83
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest

84. Routing
84
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
{
"ip": "10.0.0.1:9001",
"port": "9001"
}

85. Routing
85
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
{
"ip": "10.0.0.1:9001",
"port": "9001",
"manifest": {
"serviceName": "Service~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
}

86. Routing
86
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest

87. Routing
87
Application~1
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest

88. Routing
88
Application~1
(when v1.0.3)
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription

89. Routing
89
Application~1
(when v1.0.3)
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}

90. Routing
90
Application~1
(when v1.0.3)
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription

91. Routing
91
Instance of
Application~1
(when v1.0.3)
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription

92. Routing
92
Instance of
Application~1
(when v1.0.3)
Router
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription

93. Routing
93
Instance of
Application~1
(when v1.0.3)
Router
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription

94. Routing
94
Router
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
Instance of
Application~1
(when v1.0.3)

95. Routing
95
Router
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
Instance of
Application~1
(when v1.0.3)

96. Routing
96
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
}
]
Router
Instance of
Application~1
(when v1.0.3)

97. Routing
97
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
}
]
Instance of
Application~1
(when v1.0.3)
Router

98. Routing
98
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
}
]
Router
Instance of
Application~1
(when v1.0.3)

99. Routing
99
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
}
]
Router
v1.1.0
Instance of
Application~1
(when v1.0.3)

100. Routing
100
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
}
]
Router
v1.1.0
Service~1 v1.1.2
Instance of
Application~1
(when v1.0.3)

101. Routing
101
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
}
]
Router
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Instance of
Application~1
(when v1.0.3)

102. Routing
102
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
}
]
Router
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Instance of
Application~1
(when v1.0.3)

103. Routing
103
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
}
]
Router
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Instance of
Application~1
(when v1.0.3)

104. Routing
104
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
},
{
"ip": “10.0.0.2",
"port": “9001",
"apiSpecificationVersion": “1.1.0"
}
]
Router
Instance of
Application~1
(when v1.0.3)
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001

105. Routing
105
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest
Subscription
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
},
{
"ip": “10.0.0.2",
"port": “9001",
"apiSpecificationVersion": “1.1.0"
}
]
Router
Instance of
Application~1
(when v1.0.3)
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001

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

107. Routing
107
Application~2
Instance of
Service~1 v1.1.2
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
10.0.0.2:9001
v1.0.3
v1.1.0
Manifest

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

109. Routing
109
Application~2
(when v1.1.0)
Instance of
Service~1 v1.1.2
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
10.0.0.2:9001
v1.0.3
v1.1.0
Manifest
Subscription
{
“applicationName": "Application~2",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.1.0"
}
]
}

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

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

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

113. Routing
113
Router
Instance of
Service~1 v1.1.2
API Service
Discovery
Instance of
Service~1 v1.0.5
10.0.0.1:9001
10.0.0.2:9001
v1.0.3
v1.1.0
{
“applicationName": "Application~2",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.1.0"
}
]
}
API Registry
Instance of
Application~2
(when v1.1.0)
Manifest
Subscription

114. Routing
114
Router
Instance of
Service~1 v1.1.2
API Service
Discovery
Instance of
Service~1 v1.0.5
10.0.0.1:9001
10.0.0.2:9001
v1.0.3
v1.1.0
{
“applicationName": "Application~2",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.1.0"
}
]
}
API Registry
Instance of
Application~2
(when v1.1.0)
Manifest
Subscription

115. Routing
115
Router
Instance of
Service~1 v1.1.2
API Service
Discovery
Instance of
Service~1 v1.0.5
10.0.0.1:9001
10.0.0.2:9001
v1.0.3
v1.1.0
{
“applicationName": "Application~2",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.1.0"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
},
{
"ip": “10.0.0.2",
"port": “9001",
"apiSpecificationVersion": “1.1.0"
}
]
API Registry
Instance of
Application~2
(when v1.1.0)
Manifest
Subscription

116. Routing
116
Router
Instance of
Service~1 v1.1.2
API Service
Discovery
Instance of
Service~1 v1.0.5
10.0.0.1:9001
10.0.0.2:9001
v1.0.3
v1.1.0
{
“applicationName": "Application~2",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.1.0"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
},
{
"ip": “10.0.0.2",
"port": “9001",
"apiSpecificationVersion": “1.1.0"
}
]
API Registry
Instance of
Application~2
(when v1.1.0)
Manifest
Subscription

117. Routing
117
Router
Instance of
Service~1 v1.1.2
API Service
Discovery
Instance of
Service~1 v1.0.5
10.0.0.1:9001
10.0.0.2:9001
v1.0.3
v1.1.0
{
“applicationName": "Application~2",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.1.0"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
},
{
"ip": “10.0.0.2",
"port": “9001",
"apiSpecificationVersion": “1.1.0"
}
]
API Registry
Instance of
Application~2
(when v1.1.0)
Manifest
Subscription

118. Routing
118
Router
Instance of
Service~1 v1.1.2
API Service
Discovery
Instance of
Service~1 v1.0.5
10.0.0.1:9001
10.0.0.2:9001
v1.0.3
v1.1.0
{
“applicationName": "Application~2",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.1.0"
}
]
}
[
{
"ip": “10.0.0.1",
"port": “9001",
"apiSpecificationVersion": “1.0.3"
},
{
"ip": “10.0.0.2",
"port": “9001",
"apiSpecificationVersion": “1.1.0"
}
]
API Registry
Instance of
Application~2
(when v1.1.0)
Manifest
Subscription

119. Summary
119

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

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

122. • Make an explicit distinction between API (endpoints) and services
• Use semantic versioning for both API specifications (OpenAPI/Swagger) and services
Summary
122

123. • Make an explicit distinction between API (endpoints) and services
• Use semantic versioning for both API specifications (OpenAPI/Swagger) and services
• Make an explicit link between service and API endpoints within a manifest*
Summary
123

124. • Make an explicit distinction between API (endpoints) and services
• Use semantic versioning for both API specifications (OpenAPI/Swagger) and services
• Make an explicit link between service and API endpoints within a manifest*
• Register instances at run-time by sending the manifest to API Service Discovery
• Get the physical addresses of your running services (instances) via API Service Discovery
Summary
124

125. • Make an explicit distinction between API (endpoints) and services
• Use semantic versioning for both API specifications (OpenAPI/Swagger) and services
• Make an explicit link between service and API endpoints within a manifest*
• Register instances at run-time by sending the manifest to API Service Discovery
• Get the physical addresses of your running services (instances) via API Service Discovery
• 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
125

126. • Make an explicit distinction between API (endpoints) and services
• Use semantic versioning for both API specifications (OpenAPI/Swagger) and services
• Make an explicit link between service and API endpoints within a manifest*
• Register instances at run-time by sending the manifest to API Service Discovery
• Get the physical addresses of your running services (instances) via API Service Discovery
• Request explicit subscriptions to API endpoints at design-time, and store them in API
Registry
• Make subscriptions available at run-time with peer-tokens*
• 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 – exploit the symmetry – and, for
both, the trick is to remember/store the version of API specification ;-)
Summary
126

127. • Make an explicit distinction between API (endpoints) and services
• Use semantic versioning for both API specifications (OpenAPI/Swagger) and services
• Make an explicit link between service and API endpoints within a manifest*
• Register instances at run-time by sending the manifest to API Service Discovery
• Get the physical addresses of your running services (instances) via API Service Discovery
• Request explicit subscriptions to API endpoints at design-time, and store them in API
Registry
• Make subscriptions available at run-time with peer-tokens*
• 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 – exploit the symmetry – and, for
both, the trick is to remember/store the version of API specification ;-)
Summary
127

128. • Make an explicit distinction between API (endpoints) and services
• Use semantic versioning for both API specifications (OpenAPI/Swagger) and services
• Make an explicit link between service and API endpoints within a manifest*
• Register instances at run-time by sending the manifest to API Service Discovery
• Get the physical addresses of your running services (instances) via API Service Discovery
• Request explicit subscriptions to API endpoints at design-time, and store them in API
Registry
• Make subscriptions available at run-time with peer-tokens*
• 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 – exploit the symmetry – and, for
both, the trick is to remember/store the version of API specification ;-)
• Extend this technique to Confidence Check and A/B testing, it’s a unified way to handle any
special routing mechanisms you want to implement ;-)
Summary
128

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

130. • Make an explicit distinction between API (endpoints) and services
• Make an explicit distinction between the interface and the code
Summary
130

131. Thank You!
Patrice Krakow, Lead Architect, APIs, ING
https://www.linkedin.com/in/patricekrakow/
@patricekrakow