Service specifications along with developer documentation are key to turning your APIs into products. A well written and standards based API contract can not only make it faster and easier to integrate but also to test and deliver a solution faster
Good API contracts help improve key software delivery metrics such as lead time through collaborative/iterative design, increase deployment frequency of integrated components and reduce time-to-market for distributed software solutions
Contracts Generated from Code (Old Way)
API contracts are created and exchanged in IT projects when developing system integrations and these contracts contain details about protocol, headers, content type, operations, information exchange, errors etc.
It natural then when dealing with commercial-off-the-shelf systems to get “pre-generated” out-of-the-box contacts however this process extends to any customizations we make on these products and we get into a habit of writing code first and then generating a service specification from it. Contracts generated from code-first were the norm earlier, especially 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)
We find that traditional generated contracts are well suited for COTS application integration projects but more modern (software) delivery practices especially around digital / customer channel experience APIs and APIs-as-products (from business capabilities) rely on design-first approach with APIs hosted on a API portal with rich documentation etc. Contacts can also be pre-written i.e. through a design process they can be documented as a “this is how we will provide the service” specification
Design-first API Contracts (Accelerates Integration Time & Quality)
The design-first API contract creation approach has the consumer and provider come together to create a definition with the provider quickly generating mocks and the consumer writing tests
Designing APIs with consumers through mocks and contract tests leads to low integration defects and reduced system integration testing (S.I.T) time and faster time to market
The opposite to this contract-first practise is no-contract or contract-after-development practice which delays the delivery pipeline in multiple ways
- slow to test: it makes consumers wait until the producers have finishing writing their code, essentially making the process sequential. during integration testing changes are equally sequential, this cycle can be long in large complex projects where new teams across vendors are working together
- slow to build: this process is not collaborative and does not suit scenarios where services are designed by consumer and provider teams together
Summary
In summary, generated service contracts are documentation and provided after code for service is created. This makes it less collaborative between providers and consumers of a service and in large complex deliveries this can lead to poor API quality and longer lead time to integration
Tooling cannot solve this problem, it is cultural. For example, automating your CI/CD pipeline to generate API contract from code is still poor practice. Design-first and then code. It is important to get into the habit of writing APIs in plain text using a markup language or using tools such as Swagger or RAML designers. The process of design must extend to sharing the design, creating mocks and working with consumers and other teams to share the design, seek feedback, iterate until the API is well socialised and understood
API design first is a shift in engineering culture and leads to accelerated integration solution delivery and a quality product
Alok Mishra 