SOA/MSA design - Isolating contract dependencies

Contract is a crucial part of any services anatomy. In a SOA/MSA approach, contracts exposes the services behaviour that consumers will rely on. This behaviour is usually exposed as series of interfaces and input/output structures and implemented by internal components. The last is usually hidden from external consumers. The previous described structure may look like this:

On this example, modules are splitted, there is only one dependency flow (internal modules doesn't know external ones), each module has Its own set of dependencies, consumers rely on abstractions (the contract), so far so good.
When consuming services through REST or SOAP, consumers will need to serialise and deserialise the structures service exposes. It means they will need to hold a copy of these structures locally in order to get this job done. Now lets say you want to avoid this structure replication through all consumers inside your company. Considering services are built following the structure illustrated before, the contract module could be splitted apart and then shared with the consumers. In this scenario, you may get ride of the structure replication issue, but will running into another. When issuing the contract module as is to consumers, they will now depend on the same libraries that contract depends, otherwise consumers wont be able to use them. What about services moving to a different library-A version that isn't compatible with previous ones? A scenario like this:

If all consumers don't upgrade to the same library-A version than service is they will be broken. More consumers you have on this model, more synchronisation between them will be needed to deploy. More services you have worst It get. The expected agility when choosing this architecture approach will be harder to achieve.
One possible solution for this problem is, accept that consumers will hold local copies and just deal with It. Accepting they will have some extra work is still better than the coupling scenario described before.
You can also design your service keeping the contract module with less dependencies as possible. It may looks like this:

This design guideline can increase services flexibility when sharing contract as library. Consumers would need be affected only contract behaviour changes.even here but there are techniques to mitigate these effects. It is also an example that being succeed on going for SOA/MSA approaches depends also on good design and architectures choices.

Requirements Discovery - The Iterative approach.

Requirement Analysis is crucial part of development of any kind of system. This is the point where Engineers start shape the solution that  is gonna be built. During this phase, they also need to consider constraints that each particular project will demand (i.e cost, risk, time,quality, schedule, etc).On  the Requirement Analysis, business and IT people start get on the same page in which regards the problems that need to be addressed.
Without a proper Requirement Analysis, certain solutions are almost impossible to be built. There are some problems that are too complex to be solved without a proper understanding. It does not means Engineers will need to spend the whole budget available just be on the same than business. Here is where the agile mindsets and the lean principles came into the show. Ok, So far, so good, but why are we still seeing problems like misunderstanding on projects where there is time and space for Requirement Analysis? There can be plenty of reasons, Each project has It's own context with different problems, but I'll talk more about one I've seen several times in different projects. As  Engineers, we frequently fail to help business, go through the right direction.
I've seen quite often on projects of any size.  You may have experienced it already in case you are able to answer some of following questions:

• As a software Engineer, have you received a list of requirements to be addressed and schedule already defined? 
• Did someone get any input from the final user who is gonna be using the system?
• Have someone thought  how complex is the architecture that needs to be built in order to attend the requirements?
• What about some business concepts  that are still hidden on this requirements list that we may realise only few months after the project is already started?

All the aspects that involve the previous questions are the people usually ignore. Basically answering these questions will lead you to the symptoms the problem. Even in projects where people say they are agile, they are not free from situation. The issue to be solved here is not the methodology but involves approach and trust.

The Iterative Approach

In order to help business to find out the right requirements, the first step is to be more involved on the Requirements Elicitation process. The Iterative approach suggests this phase happens by constantly getting feedback from business. There are two main advantages by following this approach to Elicit requirements:

• Engineers and Business people on the same page: By Applying series Engineering techniques, we can help business to find out the right requirements to solve the problem they have. Engineers and business tend to be on the same page once they get constant feedback from each other in which regards the how problems  will be addressed and  technical challenges around them.
• Just enough analysis - As far it is a iterative process, business can see the list of requirements as they are being formed and they understand the challenges around them. They can decide the the right time stop and go forward with the release. On this way, you wont spend the whole budget available on the requirement analysis.
• Looking for the right Architecture  - Make business understand the challenges sometimes pass through making proves that the architecture chosen will work as expected. By doing POCs, you can get these answers before making calls that will involve more money and risk.

The Iterative approach can actually be something continuous. It means the process can be repeated as soon you reach the Implementation phase. It also means you can go back to the modelling step once the result from the POCs does not attend the expectations. This approach works pretty well on cases where teams are looking for a MVP, for instance. It also means the cycle can restart as soon you  reach the implementation phase.(i.e plan the next release).

In order to make this approach works, collaboration is mandatory. Engineers needs to get feedback from people that fully understand the business and the problems they are trying to solve, otherwise the chances of wasting resources and time building a solution that wont attend the business expectations is high.

Creating good interfaces - The Law of Demeter

For the ones who are used to the OOP approach, the term Interface,
may relates to a structure that will determine the behaviour that other structures will assume. However, when talking about Software Engineering concepts they are more than that. They help to define Software abstractions that can be widely used in a software system. Interfaces can also be seen as what structures exposes (i.e make public), to the world. Once you make something public, you're creating a chance to other structures rely on and from this point, you'll need to maintain this relationship.
Such definition help us to understand why some software implementations are so hard o maintain.
Sometimes people don't get it right and make things public when they actually should not. Structures that exposes functionality more than needed, are actually creating a new chance to be coupled to other structures. More coupling means a software that is hard to change . A software that is hard to change is expansive. A software that is expansive... well, you may know what is gonna happen from this point...

The Law of Demeter

It is a Software Design technique that aims  to help create low coupled structures. It's based on the Information Hiding principle where structures know less as possible about each other.  It states that structures should only "talk" with his "close friends" not with strangers. Even when talking with "friends", they should avoid go into "details" about how they internally do things.
As far you manage to create a solution where structures don't know about how internally each other work, you are gonna create a solution that is more susceptible to change. It is certainly a property we look for when creating any software solution.

The problem

To understand the solution, would be better firstly understand the problem. Consider the following:

On the previous example, ClassA has a given responsibility. However, it exposes it's internal details like the ClassB usage. The scenario is even worst once ClassB also exposes the need of use ClassC. This last has actually a functionality that everyone else seems to be interested in. Here everybody knows everybody, this is actually creating a weak dependency chain. As far this system grows, other structures can do the same as ClassA, making the  whole system more coupled and harder to maintain. Here all classes are violating the Demeters's Law. More than that, they don't have good Interfaces.

The Solution

Good interfaces don't reveal its internal implementation details, they expose only what is enough to it's consumers, It provides more flexibility in which regards internal changes once the coupling between structures is well managed. Looking  at the previous solution, it stands out a design flaw once AnotherClass is using ClassC through ClassA and ClassB.
A possible solution would make ClassA manage the calls in a such way that ClassB and ClassC wouldn't need talk to each other. ClassA could also expose the functionality in a such way that AnotherClass wouldn't need to know any other internal structure.

Internal details in all classes are not exposed anymore to AnotherClass. Differently than the previous solution, small internal changes on ClassC are unlikely to break all other classes . The previous chain dependency is now broken into a more composable solution.

Pros

• Low coupling. A solution that is simpler to maintain 
• Interfaces that are simpler to use 
• Improvement on the software testability once internal dependencies are no exposed.

Cons

• It is common see on the web definitions that the Demeter's Law is a matter of counting the "dots" between method calls (i.e more than two dots violates the law). Look at this direction only can be pointless. Fluent Interfaces is an example that this definition alone can be wrong. The Law should be read as a low coupling principle than other thing. 
• The Demeter's law issue lives on its own name. It's stated as a law but does not means it never needs to be violated. In cases where the changes on the design aren't worth compared with the benefits, would be ok live with it for a while. A good code/design pratic would help you and your team put a light on this.

Related links: 

• Pure OO, Inversion of Control(IoC) + Dependency Injection(DI) and The Cake Pattern(FP): Whats really matters?
• Inheritance + Mixins *with* another solution