Translate

September 3, 2016

Architecture Principle - Service Interface Compatibility Principle

Architecture principles are ground rules by which we develop our software. This ranges from ways of working to styles of coding, from software decomposition to business compliance, from infrastructure choices to security implementations. As you can see, it covers pretty much everything related to the development of business value, online, offline and internal.

Description

The typical SOA application landscape is defined by services. Through service orchestration the behavior of (online) services is implemented, business value is created. A service consists of two parts;
  1. The implementation of the service, 
  2. The interface of the service. 
Both components have their own respective life-cycle. Resulting in a situation where through time the implementation of a service is evolving typically to support evolving non-functional requirements. For example to evolve from a relational database to a NoSQL database. Or from home-grown development to the use of an online service. Analogous, the service interface can evolve over time as well, typically because the resource it represents evolves over time. For example the amount of data captured about a customer can increase over time from just a name and number to also include an email address, date of birth and marital status.

Service implementations typically change because of (more) technically driven reasons, will service interfaces typically change because of (more) business driven reasons.
Where as the service implementation is more of a service internal discussion, i.e. how the service is implemented is irrelevant as long as the defined behavior is provided, the service interface is a service external discussion, i.e. how the service can be consumed is relevant to whomever uses the service. Thus, the service interface must be kept as stable as possible, i.e. when the service changes, the interface should stay relevant for existing users and become relevant for new users.
Service interfaces can change for three reasons, that have to be factored in when complying to this principle:
  1. The resource represented by the service becomes richer, i.e. fields are added. In this case there is no impact to existing consumers. Provided that the the consumer abides by the principle that 'Unknown makes Ignored', in other words, the consumer will ignore any fields that it wasn't aware off. For example, with a Person resource that contains a Name and a Phone number, the new version also holds and email address.
  2. The resource represented by the service syntactically changes, i.e. existing fields in the resource are for example renamed because of an enrichment of the resource data. For example, with a Person resource that contains a Name and a Phone number, the new version renames the Phone number to Business phone and adds a new field Mobile number.
  3. The semantics of a resource changes although the data doesn't necessarily changes. For example a Person resource becomes a Law Enforcement Agent as all captured information pertains agents in law enforcement.



Keep in mind that the service interface is a contract, it is not just the technical procedure/function call or the URI to access the service, but also the description of the input and output values. Their constraints, limitations etc. Hence the reference to 'behavior' in the text above. For more on behavior see my post Oh Behave! How JIRA turned into a Veggie Salad.

Rationale

Since a service doesn't know about its consumers, the Producers make no Assumptions about Consumers Principle, it is unknown what the consequences are of changing the interface of the service. And therefore it is impossible to quantify the impact of such a change, hence the viability of that change is extremely hard to define. So the interface can not change, or rather, changes to the interface may not impos an impact on any of the consumers.

Implication

The implication of this principle relates to both the service as well as the consumer of the service. In all cases, the old interface should stay available for those consumers that rely on the old interface.

Producer implication

Service interfaces are to limit the impact of change, meaning that syntactic changes to the resource are to be implemented by extending the resource, i.e. adding fields, instead of changing the existing resource, i.e. changing fields. This caters for changes 1 and 2 as described above. Service interfaces that require a semantic change, i.e. the change defined in 3 (above), in fact result a new resource, and hence the identified of the resource should change.

Consumer implication

Consumers must abide the principle of 'Unknown means ignored', hence any information in a resource that is unknown, should be ignored.

References

Your API versioning is wrong, which is why I decided to do it 3 different wrong ways
VERSIONING REST WEB SERVICES
Versioning RESTful Services