Enterprise Microservices Design [Part 4: External Architecture Zone]
Broadly speaking, the external architecture of microservices is anything outside the microservices infrastructure. These include the clients trying to communicate with the microservices and the services the microservices are trying to reach out to that are hosted by 3rd party organizations.
When microservices are communicating with external architecture components we term the communication as north-south traffic. In general north-south traffic can be classified into two types,
- The client reaches out to microservice to process data
- Microservices reach out to outer architecture zone for data and services
4.1 Client to Microservices Communication
An API is a defined set of rules, commands, permissions, or protocols that allow users and applications to interact with — and access data from — a specific application or microservice. When connecting microservices to create a microservices-based application, APIs define the rules that limit and permit certain actions, interactions, commands, and data-sharing between individual services.
One of the most popular types of APIs for building microservices applications is known as “RESTful API” or “REST API.” REST API is a popular standard among developers because it uses HTTP commands, which most developers are familiar with and have an easy time using. Here are the defining characteristics of RESTful API:
- An API that uses the REST (representational state transfer) model.
- Relies on HTTP coding which is familiar to web developers.
- Uses SSL (Secure Sockets Layer) encryption.
- Language agnostic in that you can use to connect apps and microservices written in different programming languages.
- REST APIs allow you to create a web application with CRUD operations (create, retrieve, update, delete).
With current MSA the client to Microservices traffic is predominantly done via RESTful API. We as developers expose RESTful API of our services and allow clients to access our APIs. The design of these RestFul API is elaborated in section Part 2. Inner Architecture Zone and communication mechanism for clients to reach microservice are covered in section Part 3. External Architecture Zone.
When exposing our service to external clients, API documentation becomes the key communication mechanism. API documentation is a technical content deliverable, containing instructions about how to effectively use and integrate with an API. It’s a concise reference manual containing all the information required to work with the API, with details about the functions, classes, return types, arguments and more, supported by tutorials and examples. API Documentation has traditionally been done using regular content creation and maintenance tools and text editors.
API design and documentation is the first step while developing microservices and the APIs are documented at using Swagger and shared to Outer Zone clients
In some scenarios, it is also a best practice to design client jars in well known coding languages that our service consumers can use to interact with our microservices.
4.2 Microservices to External Services Communication
Often we have requirements for microservices to communicated to external services and there are numerous challenges associated with it.
- Each external client needs to communicate with a different protocol (REST, SOAP, MQ, etc..)
- Each external client has different, request and response structure and error reporting mechanism
- Each external client has a different security mechanism
- More often two or more microservices need to communicate with the same client resulting in duplication of code across microservices
With the above challenges in mind, A good design is to maintain a separate client project that abstracts out the code to handle the security, errors, request, and response communication with the client. Have individual microservices requiring to communicate with a common client use this client project to facilitate communication.
The client project thus created should adhere to the following structure
4.2.1 Versioning
All Client projects should follow the following convention for the version
<Major Version>.<Minor Version>.<Build Version>
Example: 2.0.1 (Major Version = 2, Minor Version = 0 , Minor Version =1)
major is incremented when there is a major revision update of the client endpoints that need corresponding updates at our consuming microservices
Example: if external client notified release of version 2 of their API endpoints
minor is incremented when the client changes need significant changes at the microservices consuming the changes.
Example: if we update the Request domain object in the client and added fields that are mandatory and needs to be sent by the consuming microservices
build is incremented when client changes don't impact the microservices consuming the changes
Example: if we update the Request domain object in the client and added fields that are non-mandatory and the consuming microservices need not send them
4.2.2 Best Practices
1) Always create API documentation for the microservices and keep it updated whenever contract changes
2) Create a separate client project for every external service microservices need to interact. Write the code generic enough so that any microservice can start using the client. Please don’t put any specific business logic inside the client Jars
