A Journey from API Versioning to Canary Release | Nordic APIs Platform Summit 2017

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)

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

A Journey from API Versioning to Canary Release 4

Why? 5

Why? 6

Why? 7 API Providers API Consumers

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!

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!

Why? 10 API Providers API Consumers API Versioning 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!

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

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

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

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

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

of Service~1 v1.0.0 100% 10% 90%

of Service~1 v1.0.0 100% 50% 50%

of Service~1 v1.0.0 100% 90% 10%

of Service~1 v1.0.0 100% 100%

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

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

• 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

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

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

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

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

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

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

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

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

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

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

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

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

API Gateway 39

API Gateway 40 Outside Inside

API Gateway 41 Outside Inside

API Gateway 42 Outside Inside Office

API Gateway 43 Outside Inside Office

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

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

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

Discovery Instance of Service~1 10.0.0.1:9001

Discovery Instance of Service~1 10.0.0.1:9001 Application~1

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

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

API Service Discovery and Client-Side Load Balancing 55

API Service Discovery and Client-Side Load Balancing 56

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

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

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

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

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

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

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

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

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

{ "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 ;-)

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

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

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

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

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

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

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

Routing 74

Routing 75 v1.0.3

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

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

Routing 78 API Registry v1.0.3

Routing 79 Service~1 API Registry v1.0.3

Routing 80 Service~1 API Registry v1.0.3 Manifest

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

Routing 82 Service~1 API Registry v1.0.3 Manifest

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

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

Registry 10.0.0.1:9001 v1.0.3 Manifest { "ip": "10.0.0.1:9001", "port": "9001" }

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

Registry 10.0.0.1:9001 v1.0.3 Manifest

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

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

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

Service~1 v1.0.5 API Registry 10.0.0.1:9001 v1.0.3 Manifest Subscription

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

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

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

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)

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)

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)

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

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)

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)

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)

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)

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

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

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

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

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

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

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

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

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

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

Summary 120

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

Summary 122

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

• 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

• 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

• 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

• 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

• 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

• 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

Summary 130

• Make an explicit distinction between the interface and the code Summary 131 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

A Journey from API Versioning to Canary Release...

A Journey from API Versioning to Canary Release | Nordic APIs Platform Summit 2017

More Decks by Patrice

Other Decks in Programming

Featured

Transcript