API Versioning for Zero Downtime | Devoxx Belgium 2017

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

Why API? 3

PSD2 4 Why API?

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

Why API? 6 ? ? ? ? Love brand

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

ing.jobs/Belgium

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

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

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

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

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

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

Why API Versioning? 16 2nd How? 1st Why? Versioning =
Handling change over time “Many API designers include versioning information (e.g., numbers in the URL, HTTP headers, or response body) without much thought about the assumption behind that practice.” RESTful Web Clients by Mike Amundsen

Why API Versioning? 17

Why API Versioning? 18 API Consumers API Providers

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

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

Why API Versioning? 21 What!? API Consumers API Providers 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 API Versioning? 22 API Versioning API Consumers API Providers
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 API Versioning? 23 DON’T API Consumers API Providers 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!

24 Why API Versioning?

25 Why API Versioning?

Meta-Model and Terminology for APIs 26

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

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 API 1 0..n 1 1

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 Service API 1 0..n 1 1 1 1..n

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. 33 Meta-Model and Terminology for APIs API endpoint API specification Service API 1 0..n 1 1 1 1..n 1

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. 34 Meta-Model and Terminology for APIs API endpoint API specification Service Service version API 1 0..n 1 1 1 1..n 1 1 0..n

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. 35 Meta-Model and Terminology for APIs API endpoint API specification Service Service version Instance API 1 0..n 1 1 1 1..n 1 1 0..n 1 0..n

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

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

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

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 39

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 40

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 41

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

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

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

Our Journey to Zero Downtime 45

Our Journey to Zero Downtime 46 Meta-Model and Terminology for
APIs

APIs API Gateway

APIs API Gateway API Service Discovery

APIs API Gateway API Service Discovery API Registry

APIs API Gateway API Service Discovery Routing API Registry

APIs API Gateway API Service Discovery Routing Canary Release API Registry

APIs Zero Downtime API Gateway API Service Discovery Routing Canary Release API Registry

APIs API Gateway API Service Discovery Routing Canary Release Zero Downtime API Registry

API Platform 55 API Gateway API Service Discovery API Registry

API Gateway 56

API Gateway 57 Outside Inside

API Gateway 58 Outside Inside

API Gateway 59 Outside Inside Office

API Gateway 60 Outside Inside Office

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

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

API Service Discovery 63

API Service Discovery and Client-Side Load Balancing 64

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

Discovery

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

API Service Discovery and Client-Side Load Balancing 68 Service~1 API
Service Discovery { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts" }

API Service Discovery and Client-Side Load Balancing 69 Instance of
Service~1 10.0.0.1:9001 API Service Discovery { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts" }

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

Logical Address Physical Address { "method": "get", "host": "api.ing.com", "urlPathTemplate":
"/accounts" } API Service Discovery and Client-Side Load Balancing 75 Instance of Service~1 10.0.0.1:9001 API Service Discovery { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts" }

"/accounts" } { "method": “get", "host": “10.0.0.1:9001", "urlPathTemplate": “/accounts" } API Service Discovery and Client-Side Load Balancing 76 { "method": “get", "host": “api.ing.com", "urlPathTemplate": “/accounts" } Instance of Service~1 10.0.0.1:9001 API Service Discovery

"/accounts" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/accounts" } API Service Discovery and Client-Side Load Balancing 77 { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts" } Instance of Service~1 10.0.0.1:9001 API Service Discovery

“/accounts" } { "method": “get", "host": “10.0.0.1:9001", "urlPathTemplate": “/accounts" } API Service Discovery and Client-Side Load Balancing 78 Instance of Service~1 10.0.0.1:9001 API Service Discovery

“/accounts" } { "method": “get", "host": “10.0.0.1:9001", "urlPathTemplate": “/accounts" } API Service Discovery and Client-Side Load Balancing 79 Instance of Service~1 10.0.0.1:9001 Instance of Application~1 API Service Discovery

Router Logical Address Physical Address { "method": “get", "host": “api.ing.com",
"urlPathTemplate": “/accounts" } { "method": “get", "host": “10.0.0.1:9001", "urlPathTemplate": “/accounts" } API Service Discovery and Client-Side Load Balancing 80 Instance of Service~1 10.0.0.1:9001 Instance of Application~1 API Service Discovery

"urlPathTemplate": “/accounts" } { "method": “get", "host": “10.0.0.1:9001", "urlPathTemplate": “/accounts" } API Service Discovery and Client-Side Load Balancing 81 Instance of Service~1 10.0.0.1:9001 Instance of Application~1 { "method": “get", "host": “api.ing.com", "urlPathTemplate": “/accounts" } API Service Discovery

"urlPathTemplate": “/accounts" } { "method": “get", "host": “10.0.0.1:9001", "urlPathTemplate": “/accounts" } API Service Discovery and Client-Side Load Balancing 85 Instance of Service~1 10.0.0.1:9001 Instance of Application~1 API Service Discovery

"urlPathTemplate": “/accounts" } { "method": “get", "host": “10.0.0.1:9001", "urlPathTemplate": “/accounts" } API Service Discovery and Client-Side Load Balancing 86 Instance of Service~1 10.0.0.1:9001 Instance of Application~1 Instance of Service~1 10.0.0.2:9001 API Service Discovery { "method": “get", "host": “api.ing.com", "urlPathTemplate": “/accounts" }

“/accounts" } { "method": “get", "host": “10.0.0.1:9001", "urlPathTemplate": “/accounts" } { "method": “get", "host": “api.ing.com", "urlPathTemplate": “/accounts" } { "method": “get", "host": “10.0.0.2:9001", "urlPathTemplate": “/accounts" } API Service Discovery and Client-Side Load Balancing 87 Router Instance of Service~1 Instance of Service~1 10.0.0.1:9001 10.0.0.2:9001 Instance of Application~1 API Service Discovery { "method": “get", "host": “api.ing.com", "urlPathTemplate": “/accounts" }

“/accounts" } { "method": “get", "host": “10.0.0.1:9001", "urlPathTemplate": “/accounts" } { "method": “get", "host": “api.ing.com", "urlPathTemplate": “/accounts" } { "method": “get", "host": “10.0.0.2:9001", "urlPathTemplate": “/accounts" } API Service Discovery and Client-Side Load Balancing 88 Router Instance of Service~1 Instance of Service~1 10.0.0.1:9001 10.0.0.2:9001 Instance of Application~1 API Service Discovery

“/accounts" } { "method": “get", "host": “10.0.0.1:9001", "urlPathTemplate": “/accounts" } { "method": “get", "host": “api.ing.com", "urlPathTemplate": “/accounts" } { "method": “get", "host": “10.0.0.2:9001", "urlPathTemplate": “/accounts" } API Service Discovery and Client-Side Load Balancing 89 Router Instance of Service~1 10.0.0.2:9001 Instance of Application~1 { "method": “get", "host": “api.ing.com", "urlPathTemplate": “/accounts" } API Service Discovery Instance of Service~1 10.0.0.1:9001

"/accounts" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/accounts" } { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts" } { "method": "get", "host": "10.0.0.2:9001", "urlPathTemplate": "/accounts" } API Service Discovery and Client-Side Load Balancing 93 Router Instance of Service~1 10.0.0.2:9001 Instance of Application~1 { "method": “get", "host": “api.ing.com", "urlPathTemplate": “/accounts" } API Service Discovery Instance of Service~1 10.0.0.1:9001

"/accounts" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/accounts" } { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts" } { "method": "get", "host": "10.0.0.2:9001", "urlPathTemplate": "/accounts" } API Service Discovery and Client-Side Load Balancing 94

API Service Discovery and Client-Side Load Balancing 95 Logical Address
Physical Address { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/accounts" } { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts" } { "method": "get", "host": "10.0.0.2:9001", "urlPathTemplate": "/accounts" }

API Service Discovery and Client-Side Load Balancing 102 Why not
DNS?

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. 105 API Service Discovery and Client-Side Load Balancing API endpoint API specification Xa.Ya.Za Service Service version Xs.Ys.Zs Instance API 1 0..n 1 1 1 1..n 1 1 0..n 1 0..n

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! 106 API Service Discovery and Client-Side Load Balancing API endpoint Service 1 1..n API 1 0..n 1

{ "method": "get", "host": "api.ing.com", "urlPathTemplate": "/payments" } API Service
Discovery and Client-Side Load Balancing 107

{ "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method":
"get", "host": "api.ing.com", "urlPathTemplate": "/payments" } API Service Discovery and Client-Side Load Balancing 108

API Service Discovery and Client-Side Load Balancing 109 Service~2 Service~1
{ "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/payments" }

Service~2 10.0.0.2:9001 Instance of Service~1 10.0.0.1:9001 { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/payments" }

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

"/payments" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/payments" } API Service Discovery and Client-Side Load Balancing 112 Instance of Service~2 10.0.0.2:9001 Instance of Service~1 10.0.0.1:9001 { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/payments" } API Service Discovery

"/payments" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/payments" } { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "post", "host": "10.0.0.2:9001", "urlPathTemplate": "/payments" } API Service Discovery and Client-Side Load Balancing 113 Instance of Service~2 10.0.0.2:9001 Instance of Service~1 10.0.0.1:9001 { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/payments" } API Service Discovery

"/payments" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/payments" } { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "post", "host": "10.0.0.2:9001", "urlPathTemplate": "/payments" } API Service Discovery and Client-Side Load Balancing 114 Instance of Service~2 10.0.0.2:9001 Instance of Service~1 10.0.0.1:9001 API Service Discovery

"/payments" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/payments" } { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "post", "host": "10.0.0.2:9001", "urlPathTemplate": "/payments" } API Service Discovery and Client-Side Load Balancing 115 Instance of Service~2 10.0.0.2:9001 Instance of Service~1 10.0.0.1:9001 API Service Discovery Router Instance of Application~1

"/payments" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/payments" } { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "post", "host": "10.0.0.2:9001", "urlPathTemplate": "/payments" } API Service Discovery and Client-Side Load Balancing 116 Instance of Service~2 10.0.0.2:9001 Instance of Service~1 10.0.0.1:9001 API Service Discovery Router Instance of Application~1 { "method": "get", "host": “api.ing.com", "urlPathTemplate": “/payments" }

"/payments" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/payments" } { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "post", "host": "10.0.0.2:9001", "urlPathTemplate": "/payments" } API Service Discovery and Client-Side Load Balancing 121 Instance of Service~2 10.0.0.2:9001 Instance of Service~1 10.0.0.1:9001 API Service Discovery Router Instance of Application~1 { "method": "post", "host": “api.ing.com", "urlPathTemplate": “/payments" }

"/payments" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/payments" } { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "post", "host": "10.0.0.2:9001", "urlPathTemplate": "/payments" } API Service Discovery and Client-Side Load Balancing 125 Instance of Service~2 10.0.0.2:9001 Instance of Service~1 10.0.0.1:9001 API Service Discovery Router Instance of Application~1

"/payments" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/payments" } { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "post", "host": "10.0.0.2:9001", "urlPathTemplate": "/payments" } API Service Discovery and Client-Side Load Balancing 126

Physical Address { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/payment" } { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "post", "host": "10.0.0.2:9001", "urlPathTemplate": "/payments" }

Physical Address { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "get", "host": "10.0.0.1:9001", "urlPathTemplate": "/payment" } { "method": "post", "host": "api.ing.com", "urlPathTemplate": "/payments" } { "method": "post", "host": "10.0.0.2:9001", "urlPathTemplate": "/payments" } DNS

Architect 131

Architect 132

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 135

API Registry 136

API Registry 137

API Registry 138 { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts"
}

}

} Swagger 2.0

} Swagger 2.0 OpenAPI/Swagger 2.0

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

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

} Swagger 2.0 OpenAPI/Swagger 2.0

} Swagger 2.0 OpenAPI/Swagger 2.0  OpenAPI 3.0

} Swagger 2.0 OpenAPI/Swagger 2.0 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

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

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

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

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

Instance of Service~1 10.0.0.1:9001 API Registry

Instance of Service~1 10.0.0.1:9001 API Provider API Registry

Instance of Service~1 10.0.0.1:9001 API Provider API Consumer API Registry

Instance of Service~1 10.0.0.1:9001 Is this service allowed to implement this API endpoint? API Provider API Consumer API Registry

Instance of Service~1 10.0.0.1:9001 Is this service allowed to implement this API endpoint? Is this application allowed to call this API endpoint? API Provider API Consumer API Registry

Instance of Service~1 10.0.0.1:9001 Manifest Is this application allowed to call this API endpoint? API Registry API Provider API Consumer

Instance of Service~1 10.0.0.1:9001 Manifest Subscription API Registry API Provider API Consumer

Instance of Service~1 10.0.0.1:9001 Manifest (Subscription) Peer-Token API Registry API Provider API Consumer

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

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

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

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

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

Subscription and Peer-Token 168

When a software package wants to call an API endpoint,
it has first to declare its intention to do so. Subscription and Peer-Token 169 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 170 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 172 API endpoint API specification Xa.Ya.Za Service Service version Xs.Ys.Zs Instance API (Subscription) Peer-Token Application

{ “applicationName": "<Name of the Application>", "endpoints": [ { "method":
"<paths/{path}/get|post|put|patch|delete from Swagger/OpenAPI>", "host": "<host from Swagger/OpenAPI>", "urlPathTemplate": "<paths/{path} from Swagger/OpenAPI>", "apiSpecificationVersion": "<info/version from Swagger/OpenAPI>" }, ... ] } Subscription and Peer-Token 173

{ “applicationName": "<Name of the Application>", "endpoints": [ { "method":
"<paths/{path}/get|post|put|patch|delete from Swagger/OpenAPI>", "host": "<host from Swagger/OpenAPI>", "urlPathTemplate": "<paths/{path} from Swagger/OpenAPI>", "apiSpecificationVersion": "<info/version from Swagger/OpenAPI>" }, ... ] } Subscription and Peer-Token 174 This is the exact same structure as the manifest ;-)

{ "applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com",
"urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.1" }, ... ] } Subscription and Peer-Token 176

API Platform 177 API Gateway API Service Discovery API Registry

API Platform 178 API endpoint

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

0..n 1 1 API Registry

0..n 1 1 API Registry API Developer Portal

API Platform 182

0..n 1 1 API Registry API Developer Portal

0..n 1 1 API Registry API Developer Portal Service 1 1..n Service~1

0..n 1 1 API Registry API Developer Portal Service 1 1..n Service~1 Manifest Manifest

0..n 1 1 API Registry API Developer Portal Service 1 1..n Service~1 Manifest Manifest Service version Xs.Ys.Zs 1 0..n

0..n 1 1 API Registry API Developer Portal Service 1 1..n Service~1 Manifest Manifest Service version Xs.Ys.Zs 1 0..n API Provider

0..n 1 1 API Registry API Developer Portal Service 1 1..n Manifest Manifest Service version Xs.Ys.Zs 1 0..n API Provider Instance 1 0..n Instance of Service~1 10.0.0.1:9001

0..n 1 1 API Registry API Developer Portal Service 1 1..n Manifest Manifest Service version Xs.Ys.Zs 1 0..n API Provider Instance 1 0..n Instance of Service~1 10.0.0.1:9001 API Service Discovery

0..n 1 1 API Registry API Developer Portal Service 1 1..n Manifest Manifest Service version Xs.Ys.Zs 1 0..n API Provider Instance 1 0..n Instance of Service~1 10.0.0.1:9001 API Service Discovery Router Instance of Application~1 API Consumer

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

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

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

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

Routing 199

Routing Conjecture 200 API endpoint API specification Xa.Ya.Za Service Service

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

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

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

Canary Release 206 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%

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

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 212

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 213

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 214

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 215

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 216

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 217

Routing 218

Routing 219 { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts" }

Routing 220 { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts" }
v1.0.3

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

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

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

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

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

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

{ "serviceName": "Service~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] }

Routing 229 v1.0.3 API Registry API Developer Portal Instance of
Service~1 v1.0.5 Manifest 10.0.0.1:9001 { "serviceName": “Service~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] }

Service~1 v1.0.5 Manifest 10.0.0.1:9001 { "serviceName": “Service~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] }

Service~1 v1.0.5 Manifest { "serviceName": “Service~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } 10.0.0.1:9001 API Service Discovery

Service~1 v1.0.5 Manifest { "serviceName": “Service~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } 10.0.0.1:9001 API Service Discovery { "ip": "10.0.0.1:9001", "port": "9001" }

Service~1 v1.0.5 Manifest { "serviceName": “Service~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } 10.0.0.1:9001 API Service Discovery { "ip": "10.0.0.1:9001", "port": "9001", "manifest": { "serviceName": "Service~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } }

Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery { "ip": "10.0.0.1:9001", "port": "9001", "manifest": { "serviceName": "Service~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } }

{ "ip": "10.0.0.1:9001", "port": "9001", "manifest": { "serviceName": "Service~1", "endpoints":
[ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } } Routing 235 v1.0.3 API Registry API Developer Portal Instance of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery

[ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } } Routing 236 v1.0.3 API Registry API Developer Portal Instance of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery

[ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } } Routing 237 v1.0.3 API Registry API Developer Portal Instance of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Application~1

[ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } } Routing 238 v1.0.3 API Registry API Developer Portal Instance of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Application~1 (when v1.0.3) Subscription

[ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } } Routing 239 v1.0.3 API Registry API Developer Portal Instance of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] }

[ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } } Routing 240 v1.0.3 API Registry API Developer Portal Instance of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] }

Router { "ip": "10.0.0.1:9001", "port": "9001", "manifest": { "serviceName": "Service~1",
"endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } } Routing 241 v1.0.3 API Registry API Developer Portal Instance of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK

"endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } } Routing 242 v1.0.3 API Registry API Developer Portal Instance of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK Peer-Token

"endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } } Routing 243 v1.0.3 API Registry API Developer Portal Instance of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK Peer-Token

"endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } } Routing 244 v1.0.3 API Registry API Developer Portal Instance of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK Peer-Token [ { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" } ]

Router Routing 245 v1.0.3 API Registry API Developer Portal Instance
of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK Peer-Token [ { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" } ]

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK Peer-Token [ { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" } ]

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK Peer-Token [ { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" } ] v1.1.0

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK Peer-Token [ { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" } ] v1.1.0 Service~1 v1.1.2 10.0.0.2:9001

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK Peer-Token [ { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" } ] v1.1.0 Service~1 v1.1.2 10.0.0.2:9001 Manifest

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK Peer-Token [ { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" } ] v1.1.0 Instance of Service~1 v1.1.2 10.0.0.2:9001 Manifest

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK Peer-Token [ { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" }, { "ip": "10.0.0.2", "port": "9001", "apiSpecificationVersion": "1.1.0" }, ] v1.1.0 Instance of Service~1 v1.1.2 10.0.0.2:9001 Manifest

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery Instance of Application~1 (when v1.0.3) Subscription { “applicationName": "Application~1", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.0.3" } ] } API SDK Peer-Token [ { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" }, { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.1.0" }, ] v1.1.0 Instance of Service~1 v1.1.2 10.0.0.2:9001 Manifest

Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery API SDK v1.1.0 Instance of Service~1 v1.1.2 10.0.0.2:9001 Manifest

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery API SDK v1.1.0 Instance of Service~1 v1.1.2 10.0.0.2:9001 Manifest Application~2

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

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery API SDK v1.1.0 Instance of Service~1 v1.1.2 10.0.0.2:9001 Manifest Application~2 (when v1.1.0) Subscription { “applicationName": "Application~2", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.1.0" } ] }

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery API SDK v1.1.0 Instance of Service~1 v1.1.2 10.0.0.2:9001 Manifest Instance of Application~2 (when v1.1.0) Subscription { “applicationName": "Application~2", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.1.0" } ] }

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery API SDK v1.1.0 Instance of Service~1 v1.1.2 10.0.0.2:9001 Manifest Instance of Application~2 (when v1.1.0) Subscription { “applicationName": "Application~2", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.1.0" } ] } Peer-Token

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery API SDK v1.1.0 Instance of Service~1 v1.1.2 10.0.0.2:9001 Manifest Instance of Application~2 (when v1.1.0) Subscription { “applicationName": "Application~2", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.1.0" } ] } Peer-Token [ { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" }, { "ip": "10.0.0.2", "port": "9001", "apiSpecificationVersion": "1.1.0" }, ]

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery API SDK v1.1.0 Instance of Service~1 v1.1.2 10.0.0.2:9001 Manifest Instance of Application~2 (when v1.1.0) Subscription { “applicationName": "Application~2", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.1.0" } ] } Peer-Token [ { "ip": "10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" }, { "ip": "10.0.0.2", "port": “9001", "apiSpecificationVersion": "1.1.0" }, ]

of Service~1 v1.0.5 Manifest 10.0.0.1:9001 API Service Discovery API SDK v1.1.0 Instance of Service~1 v1.1.2 10.0.0.2:9001 Manifest Instance of Application~2 (when v1.1.0) Subscription { “applicationName": "Application~2", "endpoints": [ { "method": "get", "host": "api.ing.com", "urlPathTemplate": "/accounts", "apiSpecificationVersion": "1.1.0" } ] } Peer-Token [ { "ip": “10.0.0.1", "port": "9001", "apiSpecificationVersion": "1.0.3" }, { "ip": “10.0.0.2", "port": “9001", "apiSpecificationVersion": "1.1.0" }, ]

Summary 263

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

Summary 265

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

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

• 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 to API Service Discovery • Get the physical address of instances at run-time via API Service Discovery Summary 268

• 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 to API Service Discovery • Get the physical address of instances at run-time 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 269

• 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 to API Service Discovery • Get the physical address of instances at run-time 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 – I like symmetry ;-) – and, for both, the trick is to remember/store the version of API specification ;-) Summary 270

• 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 to API Service Discovery • Get the physical address of instances at run-time 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 – I like symmetry ;-) – and, for both, the trick is to remember/store the version of API specification ;-) Summary 271

• 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 to API Service Discovery • Get the physical address of instances at run-time 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 – I like symmetry ;-) – and, for both, the trick is to remember/store the version of API specification ;-) • Extend this technique to other strategies for Canary Release, Confidence Check, A/B testing, … it’s a unified way to handle any special routing mechanisms you want to implement ;-) Summary 272

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

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

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

API Versioning for Zero Downtime | Devoxx Belgi...

API Versioning for Zero Downtime | Devoxx Belgium 2017

More Decks by Patrice

Other Decks in Programming

Featured

Transcript