API Contract: Generated vs Designed

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!




Leave a Comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s