Presentation given at Nordic APIs Platform Summit in Stockholm, the 10th of October 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
Nordic APIs – The 2017 Platform Summit
Stockholm | 2017, October 10 (2.2.1)

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. Why?
6

7. Why?
7
API Providers API Consumers

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

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

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

11. Why?
11
API Providers API Consumers
want to change their
APIs as soon as they
have a new brilliant idea
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!
DON’
T

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

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

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

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

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

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

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

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

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

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

22. Meta-Model and Terminology for APIs
22

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
Service
API

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

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

31. • 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.
31
Meta-Model and Terminology for APIs
API endpoint
API specification
Service
Service version
Xs.Ys.Zs
Instance
API

32. • 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.
32
Meta-Model and Terminology for APIs
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API

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

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

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

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

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

39. API Gateway
39

40. API Gateway
40
Outside Inside

41. API Gateway
41
Outside Inside

42. API Gateway
42
Outside Inside Office

43. API Gateway
43
Outside Inside Office

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

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

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

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

48. API Service Discovery and Client-Side Load Balancing
48
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
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
Application~1

51. API Service Discovery and Client-Side Load Balancing
51
Router
API Service
Discovery
Instance of
Service~1
10.0.0.1: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
Router
Instance of
Service~1
API Service
Discovery
Instance of
Service~1
10.0.0.1:9001
10.0.0.2:9001
Application~1

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

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

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

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

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

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.
The Manifest
59
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
Manifest

60. 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
60
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
Manifest

61. {
"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
61

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

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.
Subscription and Peer Token
63
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
SubscriptionApplication

64. 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 created.
Subscription and Peer Token
64
API endpoint
API specification
Xa.Ya.Za
Service
Service version
Xs.Ys.Zs
Instance
API
SubscriptionApplication

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

66. {
"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
66
This is the exact same structure as the manifest ;-)

67. 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
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)
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
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)
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
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)
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
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
the API Registry and the API Service Discovery ;-)
Routing
72

73. 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 from both
API Registry and API Service Discovery ;-)
Routing
73

74. Routing
74

75. Routing
75
v1.0.3

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

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

78. Routing
78
API Registry
v1.0.3

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

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

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

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

83. Routing
83
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

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"
}

86. Routing
86
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"
}
]
}
}

87. Routing
87
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
API Service
Discovery
Instance of
Service~1 v1.0.5
API Registry
10.0.0.1:9001
v1.0.3
Manifest

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

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
{
“applicationName": "Application~1",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.0.3"
}
]
}

91. Routing
91
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)
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
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

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
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)

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"
}
]
Router
Instance of
Application~1
(when v1.0.3)

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"
}
]
Instance of
Application~1
(when v1.0.3)
Router

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
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
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
Service~1 v1.1.2
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"
}
]
Router
v1.1.0
Instance of
Service~1 v1.1.2
10.0.0.2:9001
Instance of
Application~1
(when v1.0.3)

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

107. Routing
107
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
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

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

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
{
“applicationName": "Application~2",
"endpoints": [
{
"method": "...",
"host": "...",
"urlPathTemplate": "...",
"apiSpecificationVersion": "1.1.0"
}
]
}

111. Routing
111
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

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
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"
}
]
}
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. Routing
119
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

120. Summary
120

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

122. • Make an explicit distinction between API (endpoints) 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
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*
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
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*
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 ;-)
Summary
128

129. • 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
129

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

131. • Make an explicit distinction between API (endpoints) and services
• Make an explicit distinction between the interface and the code
Summary
131
Click to edit Master title style

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

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

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