Contractualise

The single biggest problem in communication is the illusion that it has taken place.

George Bernard Shaw

Nom

Contractualise

Statement

To interact, services share contracts, not their business logic and data. Thus, the business logic and data of a service can only be accessed through its contracted interfaces.

These interfaces can be graphical (GUI) or programmatic (API).

Rationale

• Prevent unintended complexity caused by hidden dependencies.
• Explain interactions between services.
• Apply the principle of empowerment and weak coupling.

Implications

• Implement interfaces based on standard protocols: e.g. REST, AMQP, MLLP, FHIR, SOAP, JMS, etc.
• Implement understandable interfaces.
• Document the interfaces.

Examples

Bad

The Patient Management service does not provide a formal interface for retrieving patient data. Therefore, external services that require this data access it via the database. As the data model is specific to the operation of the Patient Management service, it is sometimes optimised. External services are therefore never guaranteed to be able to retrieve the data in a reliable way.

Good

The Patient Management department publishes and documents its interfaces to its human and machine users. A change in the internal logic of the Patient Management service does not affect the other services. Any change in the interface contract leads to communication of the new interface contract to the consumers, who are explicitly known.