59
CHAPTER 3 | Architecting container and microservice-based applications
Creating,
evolving, and versioning microservice APIs
and contracts
A microservice API is a contract between the service and its clients. You’ll be able to evolve a
microservice independently only if you do not
break its API contract, which is why the contract is so
important. If you change the contract, it will impact your client applications or your API Gateway.
The nature of the API definition depends on which protocol you’re using. For instance, if you’re using
messaging (like
AMQP
), th
e API consists of the message types. If you’re using HTTP and RESTful
services, the API consists of the URLs and the request and response JSON formats.
However, even if you’re thoughtful
about your initial contract, a service API will need to change over
time. When that happens
—
and especially if your API is a public API
consumed by multiple client
applications
—
you typically can’t force all clients to upgrade to your new API contract. You usually
need to incrementally deploy new versions of a service in a way that both old and new versions of a
service contract are running simultaneously. Therefore, it’s important
to have a strategy for your
service versioning.
When the API changes are small, like if you add attributes or parameters to your API,
clients that use
an older API should switch and work with the new version of the service. You might be able to provide
default values for any missing attributes that are required, and the clients might be able to ignore any
extra response attributes.
However, sometimes you need to make major and incompatible changes to a service API. Because
you might not be able to force client applications or services to upgrade immediately to the new
version, a service must support older versions of the API for some period. If you’
re using an HTTP-
based mechanism such as REST, one approach is to embed the API version number
in the URL or into
an HTTP header. Then you can decide between implementing both versions of the service
simultaneously within the same service instance, or deploying different instances
that each handle a
version of the API. A good approach for this functionality is the
Mediator pattern
(for example,
MediatR library
) to decouple the different implementation versions into independent handlers.
Finally, if you’re using a REST architecture,
Hypermedia
is the best solution for versioning your services
and allowing evolvable APIs.
Dostları ilə paylaş: 
