Service specifications are key to a well designed and well architected domain or technical service. These contracts contain details about have operations you can do, the information exchange structure and other details surrounding the request
Two key aspects of contract design have nothing to do with whats in them, rather around when and how contracts are design. The lifcyle of a service contract is equally, if not more, important than its contents
Contracts as Generated documents
Contracts generated from code-first were the norm earlier, especiallt when building SOAP services where WSDL was generated using tools from code
The generated contract creates a dependency on the service writer and generator before consumers can use a contract. There can also be multiple copies of the contract – the actual (runtime) and the shared (copy)
If the provider makes changes over time to the core service, between the time the new contract is generated and the client changes are made – the service consumption may be broken as what is being provided is not the same as the original contract
Also this process is not collaborative and does not suit scenarios where services are designed by consumer and provider teams together
- Generated service contracts are documentation and not a contract
- A contract is a collaborative effort between Providers and Consumers
- An API Gateway or tool cannot solve this problem, it is cultural
- The above process in real-world creates layers of responsibility – Service provider, Service consumer and middleware provider etc making it harder to test APIs
This was one of the problems with SOA style implementations – the “Enterprise Business Service (EBS)” was owned by the middleware team and “Application Business Services (ABS)” was owned by the services teams.
Alternative Approach: Collaboratively design contracts
Collaborative contracts that help define what a service should do!
This contract is used by Consumers to build their client-code and more importantly the providers use the contract to build the service and test it!