
Teams must employ appropriate communication techniques, including deprecation
and turn-down notices, to ensure awareness of changes to microservice
contracts

depreciation notice

One of the most important aspects of microservices-based applications is the
ability to deploy microservices completely independent of one another. To
achieve this independence, each microservice must provide a versioned,
well-defined contract to its clients, which are other microservices.
Each service must not break these versioned contracts until it's known that no
other microservice relies on a particular, versioned contract.

contract versions

It's important to understand the difference between a breaking change and a
non-breaking change. Breaking changes are often subtractive, meaning they take
away some part of the request or response document. Changing the shape of the
document or changing the name of the keys can introduce a breaking change. New
required arguments are always breaking changes. Breaking changes can also occur
if the behavior of the microservice changes.

Non-breaking changes tend to be additive. A new optional
request argument, or a new additional section in the response document are
non-breaking changes. In order to achieve non-breaking changes, the choice of
on-the-wire serialization is essential. Many serializations are friendly to
non-breaking changes: JSON, Protocol Buffers, or Thrift. When deserialized,
these serializations silently ignore extra, unexpected information. In
dynamic languages, the extra information simply appears in the deserialized
object.

breaking=subtractive non-breaking=additive

<div dir="ltr">

Python <a href="https://cloud.google.com/appengine/docs/standard/python/designing-microservice-api" title="View this page in the Python 2.7 runtime" track-type="languageSwitcherNav" track-metadata-position="standardEnvironment" track-name="python" dir="ltr">2.7</a>/3.7
|Java 8/11
|PHP <a href="https://cloud.google.com/appengine/docs/standard/php/designing-microservice-api" title="View this page in the PHP 5 runtime" track-type="languageSwitcherNav" track-metadata-position="standardEnvironment" track-name="php" dir="ltr">5</a>/7
|Ruby
|Go 1.11/1.12+
|Node.js

</div>Microservices on App Engine typically call one another using HTTP-based RESTful
APIs. It is also possible to invoke microservices in the background by using
Task Queues, and the API design tenets described here apply. It's important to
follow certain patterns in order to ensure your microservices-based application
is stable, secure, and performs well.<h2 data-text="Using strong contracts" tabindex="0" is-upgraded="">Using strong contracts</h2>One of the most important aspects of microservices-based applications is the
ability to deploy microservices completely independent of one another. To
achieve this independence, each microservice must provide a versioned,
well-defined contract to its clients, which are other microservices.
Each service must not break these versioned contracts until it's known that no
other microservice relies on a particular, versioned contract. Keep in mind that
other microservices may need to roll back to a previous code version that
requires a previous contract, so it's important to account for this fact in your
deprecation and turn-down policies.A culture around strong, versioned contracts is probably the most challenging
organizational aspect of a stable, microservices-based application. Development
teams must internalize an understanding of a breaking change versus a
non-breaking change. They must know when a new major release is required.
They must understand how and when an old contract can be taken out of service.
Teams must employ appropriate communication techniques, including deprecation
and turn-down notices, to ensure awareness of changes to microservice
contracts. While this may sound daunting, building these practices into
your development culture will yield great improvements in velocity and quality
over time.<h2 data-text="Addressing microservices" tabindex="0" is-upgraded="">Addressing microservices</h2>Services and code versions can be directly addressed. As a result, you can deploy
new code versions side-by-side with existing code versions, and you can test new
code before making it the default serving version.Each App Engine project has a default service, and each service has a default code
version. To address the default service of the default version of a project,
use the following URL: 

<code translate="no" dir="ltr">https://<var dir="ltr">PROJECT_ID</var>.<var dir="ltr"><a href="https://cloud.google.com/appengine/docs/standard/java/designing-microservice-api#appengine-urls" data-modal-dialog-id="regional_url" track-type="progressiveHelp" track-name="modalHelp" track-metadata-goal="regionalURL" dir="ltr">REGION_ID</a></var>.r.appspot.com</code>If you deploy a service named <code translate="no" dir="ltr">user-service</code>, you can access the default serving
version of that service using the following URL:<PRE><code translate="no" dir="ltr">&lt;code&gt;https://user-service-dot-my-app.&lt;var&gt;&lt;a href="#appengine-urls"
 style="border-bottom: 1px dotted #999" class="devsite-dialog-button"
 data-modal-dialog-id="regional_url" track-type="progressiveHelp"
 track-name="modalHelp"
 track-metadata-goal="regionalURL"&gt;REGION_ID&lt;/a&gt;&lt;/var&gt;.r.appspot.com&lt;/code&gt;
</code></PRE>If you deploy a second, non-default code version named <code translate="no" dir="ltr">banana</code>
to the <code translate="no" dir="ltr">user-service</code> service, you can directly access that code version
using the following URL:<PRE><code translate="no" dir="ltr">&lt;code&gt;https://banana-dot-user-service-dot-my-app.&lt;var&gt;REGION_ID&lt;/a&gt;&lt;/var&gt;.r.appspot.com&lt;/code&gt;
</code></PRE>Note that if you deploy a second, non-default code version named <code translate="no" dir="ltr">cherry</code> to the
<code translate="no" dir="ltr">default</code> service, you can access that code version by using the following URL:<PRE><code translate="no" dir="ltr">&lt;code&gt;https://cherry-dot-my-app.&lt;var&gt;REGION_ID&lt;/a&gt;&lt;/var&gt;.r.appspot.com&lt;/code&gt;
</code></PRE>App Engine enforces the rule that the names of code versions in the default
service cannot collide with service names.Direct-addressing specific code versions should only be used for smoke
testing and to facilitate A/B testing, rolling forward,
and rolling back. Instead your client code should address only the default,
serving version of either the default service or a specific service:<PRE><code translate="no" dir="ltr">
<code translate="no" dir="ltr">https://<var dir="ltr">PROJECT_ID</var>.<var dir="ltr"><a href="https://cloud.google.com/appengine/docs/standard/java/designing-microservice-api#appengine-urls" data-modal-dialog-id="regional_url" track-type="progressiveHelp" track-name="modalHelp" track-metadata-goal="regionalURL" dir="ltr">REGION_ID</a></var>.r.appspot.com</code>

<code translate="no" dir="ltr">https://<var dir="ltr">SERVICE_ID</var>-dot-<var dir="ltr">PROJECT_ID</var>.<var dir="ltr"><a href="https://cloud.google.com/appengine/docs/standard/java/designing-microservice-api#appengine-urls" data-modal-dialog-id="regional_url" track-type="progressiveHelp" track-name="modalHelp" track-metadata-goal="regionalURL" dir="ltr">REGION_ID</a></var>.r.appspot.com</code>
</code></PRE>This addressing style allows the microservices to deploy new versions of
their services, including bug fixes, without requiring any changes to clients.<h2 data-text="Using API versions" tabindex="0" is-upgraded="">Using API versions</h2>Every microservice API should have a major API version in the URL, such as:<PRE>/user-service/v1/</PRE>This major API version clearly identifies in the logs which API version of the
microservice is being called. More importantly, the major API version yields
different URLs, so that new major API versions can be served side-by-side with
old major API versions:<PRE>/user-service/v1/
/user-service/v2/</PRE>There is no need to include the minor API version in the URL because minor API
versions by definition will not introduce any breaking changes. In fact,
including the minor API version in the URL would result in a proliferation of
URLs and cause uncertainty about the ability of a client to move to a new minor
API version.Note that this article assumes a continuous integration and delivery environment
where the master branch is always being deployed to App Engine.
There are two distinct concepts of version in this article:<UL><LI>Code version, which
maps directly to an App Engine service version and represents a
particular commit tag of the master branch.</LI><LI>API version, which
maps directly to an API URL and represents the shape of the
request arguments, the shape of the response document,
and the API behavior.</LI></UL>This article also assumes that a single code deployment will implement both old
and new API versions of an API in a common code version. For example, your
deployed master branch might implement both <code translate="no" dir="ltr">/user-service/v1/</code> and
<code translate="no" dir="ltr">/user-service/v2/</code>. When rolling out new minor and patch versions,
this approach allows you to split traffic
between two code versions independently of the API versions that the code
actually implements.Your organization can choose to develop your
<code translate="no" dir="ltr">/user-service/v1/</code> and <code translate="no" dir="ltr">/user-service/v2/</code>
on different code branches; that is, no one code deployment will
implement both of these at the same time. This model is also
possible on App Engine, but to split traffic
you would need to move the major API version into the service name itself.
For example, your clients would use the following URLs:<PRE>http://user-service-v1.my-app.<var dir="ltr"><a href="https://cloud.google.com/appengine/docs/standard/java/designing-microservice-api#appengine-urls" data-modal-dialog-id="regional_url" track-type="progressiveHelp" track-name="modalHelp" track-metadata-goal="regionalURL" dir="ltr">REGION_ID</a></var>.r.appspot.com/user-service/v1/
http://user-service-v2.my-app.<var dir="ltr">REGION_ID</var>appspot.com/user-service/v2/
</PRE>The major API version moves into the service name itself, such as
<code translate="no" dir="ltr">user-service-v1</code> and <code translate="no" dir="ltr">user-service-v2</code>.
(The <code translate="no" dir="ltr">/v1/</code>, <code translate="no" dir="ltr">/v2/</code> parts of the
path are redundant in this model and
could be removed, though they still may be useful in log analysis.)
This model requires a bit more work because it likely requires
updates to your deployment scripts to deploy new services on
major API version changes. Also, be aware of the
<a href="https://cloud.google.com/appengine/docs/standard/java/an-overview-of-app-engine" dir="ltr">maximum number of allowed services</a>
per App Engine application.<h2 data-text="Breaking versus non-breaking changes" tabindex="0" is-upgraded="">Breaking versus non-breaking changes</h2>It's important to understand the difference between a breaking change and a
non-breaking change. Breaking changes are often subtractive, meaning they take
away some part of the request or response document. Changing the shape of the
document or changing the name of the keys can introduce a breaking change. New
required arguments are always breaking changes. Breaking changes can also occur
if the behavior of the microservice changes.Non-breaking changes tend to be additive. A new optional
request argument, or a new additional section in the response document are
non-breaking changes. In order to achieve non-breaking changes, the choice of
on-the-wire serialization is essential. Many serializations are friendly to
non-breaking changes: JSON, Protocol Buffers, or Thrift. When deserialized,
these serializations silently ignore extra, unexpected information. In
dynamic languages, the extra information simply appears in the deserialized
object.Consider the following JSON definition for the service <code translate="no" dir="ltr">/user-service/v1/</code>:<PRE><code translate="no" dir="ltr">{
 "userId": "UID-123",
 "firstName": "Jake",
 "lastName": "Cole",
 "username": "jcole@example.com"
}
</code></PRE>The following breaking change would require re-versioning the service as
<code translate="no" dir="ltr">/user-service/v2/</code>:<PRE><code translate="no" dir="ltr">{
 "userId": "UID-123",
 "name": "Jake Cole", # combined fields
 "email": "jcole@example.com" # key change
}
</code></PRE>However, the following non-breaking change doesn't require a new version:<PRE><code translate="no" dir="ltr">{
 "userId": "UID-123",
 "firstName": "Jake",
 "lastName": "Cole",
 "username": "jcole@example.com",
 "company": "Acme Corp." # new key
}
</code></PRE><h2 data-text="Deploying new non-breaking minor API versions" tabindex="0" is-upgraded="">Deploying new non-breaking minor API versions</h2>When deploying a new minor API version, App Engine allows for the new code
version to be released side-by-side with the old code version. On App Engine,
though you can directly address any of the deployed versions, only one version
is the default serving version; recall that there is a default serving version
for each service. In this example, we have our old code version, named <code translate="no" dir="ltr">apple</code>
which happens to be the default serving version, and we deploy the new code
version as a side-by-side version, named <code translate="no" dir="ltr">banana</code>. Note that the microservice
URLs for both are the same <code translate="no" dir="ltr">/user-service/v1/</code> since we are deploying a
non-breaking minor API change.App Engine provides mechanisms to automatically migrate the traffic from <code translate="no" dir="ltr">apple</code>
to <code translate="no" dir="ltr">banana</code> by marking the new code version <code translate="no" dir="ltr">banana</code> as the default serving
version. When the new default serving version is set, no new requests will be
routed to <code translate="no" dir="ltr">apple</code> and all new requests will be routed to <code translate="no" dir="ltr">banana</code>. This is how
you roll forward to a new code version that implements a new minor or patch API
version with no impact to client microservices.In the event of an error, rolling back is achieved by reversing the above
process: set the default serving version back to the old one, <code translate="no" dir="ltr">apple</code> in our
example. All new requests will route back to the old code version and no new
requests will route to <code translate="no" dir="ltr">banana</code>. Note that in-progress requests are allowed
to complete.App Engine also provides the ability to direct only a certain percentage of your
traffic to your new code version; this process is often called a canary
release process and the mechanism is called
<a href="https://cloud.google.com/appengine/docs/developers-console#traffic-splitting" dir="ltr">traffic splitting</a>
in App Engine.
You can direct 1%, 10%, 50%, or any percentage of traffic you'd like against
your new code versions, and you can adjust this amount over time. For example,
you could roll out your new code version over 15 minutes, slowly increasing the
traffic and watching for any issues that might identify that a rollback is
required. This same mechanism lets you A/B test two code versions: set the
traffic split to 50% and compare the performance and error rate characteristics
of the two code versions to confirm expected improvements.The following image shows traffic-splitting settings in the
Cloud Console:<img alt="Traffic splitting settings in the Google Cloud Console" src="https://cloud.google.com/solutions/images/microservices-console-traffic-splitting.png" width="392" height="396"><h2 data-text="Deploying new breaking major API versions" tabindex="0" is-upgraded="">Deploying new breaking major API versions</h2>When you deploy breaking, major API versions, the process of rolling forward and
rolling back is the same as for non-breaking, minor API versions. However, you
typically won't perform any traffic splitting or A/B tests because the breaking
API version is a newly released URL, such as
<code translate="no" dir="ltr">/user-service/v2/</code>. Of course, if you've changed the underlying
implementation of your old major API version, you may still want to use
traffic splitting to test that your old major API version continues to
function as expected.When deploying a new API major version, it's important to remember that old
major API versions might also still be serving. For example, <code translate="no" dir="ltr">/user-service/v1/</code>
might still be serving when <code translate="no" dir="ltr">/user-service/v2/</code> is released. This fact is an
essential part of independent code releases. You might only turn-down old major
API versions after you've verified that no other microservices require them,
including other microservices that may need to roll back to an older code
version.As a concrete example, imagine that you have a microservice, named <code translate="no" dir="ltr">web-app</code>,
that depends on another microservice, named <code translate="no" dir="ltr">user-service</code>. Imagine that
<code translate="no" dir="ltr">user-service</code> needs to change some underlying implementation that will
make it impossible to support the old major API version that <code translate="no" dir="ltr">web-app</code>
is currently using, such as collapsing <code translate="no" dir="ltr">firstName</code> and <code translate="no" dir="ltr">lastName</code>
into a single field called <code translate="no" dir="ltr">name</code>. That is,
<code translate="no" dir="ltr">user-service</code> needs to turn-down an old major API version.In order to accomplish this change, three separate deployments must be made:<UL><LI>First, <code translate="no" dir="ltr">user-service</code> must deploy <code translate="no" dir="ltr">/user-service/v2/</code> while still supporting
<code translate="no" dir="ltr">/user-service/v1/</code>. This deployment may require temporary code to be
written to support backwards compatibility, which is a common consequence in
microservices-based applications</LI><LI>Next, <code translate="no" dir="ltr">web-app</code> must deploy updated code that changes its dependency from
<code translate="no" dir="ltr">/user-service/v1/</code> to <code translate="no" dir="ltr">/user-service/v2/</code></LI><LI>Finally, after the <code translate="no" dir="ltr">user-service</code> team has verified that <code translate="no" dir="ltr">web-app</code>
no longer requires <code translate="no" dir="ltr">/user-service/v1/</code> and that <code translate="no" dir="ltr">web-app</code> does not
need to roll back, the team can deploy code that removes the old
<code translate="no" dir="ltr">/user-service/v1/</code> endpoint and any temporary code they needed
to support it.</LI></UL>While all this activity may seem onerous, it's an essential process in
microservices-based applications and is precisely the process that enables
independent development release cycles. To be clear, this process appears
to be quite dependent, but importantly each step above can occur on independent
timelines, and rolling forward and rollback occurs within the scope of a single
microservice. Only the order of the steps is fixed and the steps could
take place over many hours, days, or even weeks.

Google Cloud delivers secure, open, intelligent, and transformative tools to help enterprises modernize for today's digital world.

Contracts, Addressing, and APIs for Microservices

depreciation notice

contract versions

breaking=subtractive non-breaking=additive

Similar ideas