DescriptionThe 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;
- The implementation of the service,
- The interface of the service.
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:
- 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.
- 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.
- 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.
Producer implicationService 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 implicationConsumers must abide the principle of 'Unknown means ignored', hence any information in a resource that is unknown, should be ignored.
ReferencesYour API versioning is wrong, which is why I decided to do it 3 different wrong ways
VERSIONING REST WEB SERVICES
Versioning RESTful Services