Microservices: The Static Contract Pitfall and how to avoid it

Allan B/H — Tue, 30 Nov 2021 16:16:16 +0000

Hi everyone! I would like to show you how The Static Contract pitfall could drive APIs to unexpected issues, and how versioning helps to avoid them. For that purpose I will be using O'Reilly's Microservices Antipatterns and Pitfalls and Microsoft site related to RESTful web API design. References were added at bottom.

But what is a pitfall?

According to Richards (2016) a pitfall is

something that was never a good idea, even from the start.

And that is the case for The Static Contract pitfall. This assumption leads APIs to be not flexible enough for contract changes in front of client applications.

The Static Contract Pitfall

Imagine having a REST API endpoint consumed by three different client applications, but one of them needs an extension of a service published. So, the API provider in order to deploy the new changes, requires to check compatibility with the others consumers. Ups! Something goes wrong, the changes imply modifying a JSON contract, then consumers will be impacted and none of them would adapt to those modifications at the same time.

It happens all the time, contracts between providers and consumers are not static. They change very often by adding new features to microservices. However, there are some strategies to keep those issues away and implement backward compatibility without breaking all clients.

Versioning strategies

Header versioning

This type of versioning allows to manage the API version by adding the version number in a custom HTTP Header. It requires that client applications use this header to specify which service version will be consumed.
Besides, it is important to consider server-side cache in case every request was stored, here using a proxy could help to reduce duplicated cache data.
In the next example is showed the creation of a new order using an api-version specified in the Custom-Header.

POST https://enterprise.domain.com/orders/123  
Custom-Header: api-version=1

URI versioning

This technique consist in defining the version of an API in the uniform resource identifier (URI). It makes very clear to know which version will be consumed for client applications.
For instance, choosing a version of a service used to retrieve an order could be done by v1 or any custom standard.
It is relevant to mention that this implementation makes harder to follow HATEOS constraint because all links associated to resources should have defined their correct version number.

GET https://enterprise.domain.com/v1/orders/123

Query string versioning

Regarding to this versioning strategy, the version goes in the query string parameter. In that case, it is recommended to establish a default version number when a client misses sending this parameter. The following example uses ?version=3 as query string.

GET https://enterprise.domain.com/orders/123?version=3

As URI strategy, the previous approach has the same issue related to implementation of HATEOS.

MediaType versioning

Finally, very closed to header versioning practice, MediaType needs to be sent in the Accept Content Type Header. Provider is responsible for handling all possible format responses with their defined versions. For example, deleting an order could be performed if version were specified in Accept header along format response required.

DELETE https://enterprise.domain.com/orders/123 
Accept: application/vnd.enterprise.domain.com.v2+json

tl;dr

Versioning strategy	Location	Some Considerations
Header	Custom HTTP header	Server-side cache issues
URI	Properly as part of URI	Very simple and clear which version is used Makes harder to implement HATEOAS
Query String	Query string param of URI	Should be defined a default version value Makes harder to implement HATEOAS
Mediatype	Accept Http header	Handle all possible format responses with their defined versions Server-side cache issues

Conclusion

Microservices have became an extended practice in software architecture, from those implementations have emerged many lesson to learn and for this reason there are several antipatterns and pitfalls to take in consideration. Learning from the experience of the others and having in mind those best practices is crucial to build a strong architecture. Here is important to evaluate the options and choose the best one according to context.

References

Richards, M. (2016). Microservices Antipatterns and Pitfalls. CA: O’Reilly Media.

Microsoft (2021). RESTful web API design. Retrieve from https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design

Microservices Patterns: Orchestration and Choreography

Allan B/H — Sat, 20 Feb 2021 21:41:27 +0000

Hi everyone! This is my first post and I'd like to share some thoughts about the differences between Orchestration and Choreography as architecture approaches in a solution based on microservices.

There are many ways to define the interaction between software components, in a microservices architecture, to have a robust result, is crucial to follow some principles of design.

That is why could be a very important tool to know about Orchestration and Choreography terms.

Orchestration

This pattern behaves like a real orchestra, where there is a central guider that coordinates all of rest of musicians in order to play a symphony. In Orchestration, a piece of software does that work and by certain number of calls, it makes possible the entire process.

According to the last image, service 1 is responsible for making the requests to other components. Those calls could be either synchronous or asynchronous. So, service 1 manages the interactions between service 2 and service 3.

In that sense, an orchestrator becomes an easy way to manage complex processes by a centralized control between each steps. So, it has all required functionalities to make a response to the client.

Most likely, Orchestration can increase the dependencies between services. Due to the existence of a single coordinator of a entire process. Usually it is delegated to this component more responsibility than others and sometimes it results in a lack of purpose and anemic model .

Summary

A single component conducts all the process (orchestrator).
Commonly, orchestrator has more responsibility that other components.
Easy way to coordinate a complex process with several steps.
If orchestrator gets so much responsibility, tends to anemic models.

Choreography

On another side, Choreography is a pattern which components communicate by themselves to complete a request. So, there is no a single conductor but each service is responsible for doing its part of the job.

The governance of services under this model could be more complex, since there are several points of failure. And evidently, it is necessary to complement the solution with a good tracing pattern.

However, Choreography provides low coupling when is implemented under a event-driven architecture (although this approach is not exclusive of that pattern). Because of this, the components designed come to be more autonomous and it allows a better reusability thus the reduce of dependencies.

Therefore, in a choreography service 1 doesn't know about the calls of service 2 and service 3.

Summary

Each service acts together to get a result with the same level of responsibility.
The interactions flow uses to be more complex.
Components are more autonomous.

tl;dr

Orchestration	Choreography
A single component conducts all the process.	Components have to act together in a coordinated way.
Orchestrator has more responsibility than other components.	Use to be a harder way to coordinate a complex process with several steps.
Orchestrator with so much responsibility tends to anemic models.	Services show a tendency to be more autonomous.

Conclusion

Orchestration and Choreography models have certain advantages and disadvantages and they are not good or bad by themselves. All depends on the requirements and technical capabilities. For that reason, it would be helpful to evaluate the pros and cons of both patterns to implement a solution that fits properly.
Finally, it is necessary to emphasize that is not kind of dichotomy between Orchestration and Choreography and they could be used in a sort of combination inside an software architecture.

References

Bruce, M., & Pereira, P. A. (2019). Microservices in action. Shelter Island, NY: Manning Publications Co.

Forem: Allan B/H

Microservices: The Static Contract Pitfall and how to avoid it

But what is a pitfall?

The Static Contract Pitfall

Versioning strategies

Header versioning

URI versioning

Query string versioning

MediaType versioning

tl;dr

Conclusion

References

Microservices Patterns: Orchestration and Choreography

Orchestration

Summary

Choreography

Summary

tl;dr

Conclusion

References