Contracts have been part of software development and architecture forever. In the SOAP days we had WSDL, but we’ve always had the concepts around ensuring backwards compatibility with 3rd party and internally built components (dll, jar packages, etc). In consideration of APIs, contracts are a vital part of API development and consumption and are used to ensure integrity between the API consumers and API service.
When describing your API contract, the decfacto standard today is the Open API Specification (formerly Swagger) which provides a common framework for describing your API technically and providing a contract specification. Typically, the API contract will describe the inputs, outputs, version, terms of service, supported methods (PUT, POST, etc), and supported responses. The contract documentation will also provide a human readable description of the purpose of the API.
APIs are typically described in YAML or JSON and also form a key part in API discoverability for your API consumers. To get familiar with API specifications, I’d recommend the free online swagger editor https://editor.swagger.io.
Architects need to concern themselves with contracts as contracts help ensure the overall integrity of the solution. In consideration of an API centric enterprise, the flow of information will go through a series of different APIs each with their own API contract specification and each developed, iteratively, over a period of time.
As an architect, it’s important to understand your current API landscape, business needs, and security and governance constraints. Ultimately, it’s the entire solution that will need to get signed off by various governance entities and generally from the CISO to ensure conformance to enterprise security standards which are of the utmost important when considering any kind of Internet accessible API program.
As the architecture is built out and begins to take form, business teams and developers will come together to create contracts. A data or system API will have a specific contract as related to accessing and updating data. It may be consumed by a business or processing API which may call other APIs and provide its own business logic. The business logic and operations performed within the API should help dictate the API contract, but ultimately, it doesn’t matter precisely what is happening inside of the API logic; the importance lies in defining what the expected output will be based on the requirements of your consumers and what the inputs to the API will be based on the needs of the API and the availability of information from the consumer in order to provide the input to successfully invoke the API.
API contracts help enforce governance because once your have an API contract defined based on the business requirements, governance comes into play to ensure that appropriate regulatory and enterprise standards are employed. It also gives developers, business, and governance the opportunity to negotiate what is really required in an API which ultimately impacts the complexity of the solution. PII (personally identifiable information) is handled differently than public data. In Europe, GDPR is a regulatory framework that must be adhered to, and in Canada, you have PIPEDA as an example. PCI-DSS is also important, and if your solution is handling any kind of payment card information, you will be required to properly audit your solution to provide PCI-DSS attestation to your clients wishing to consume your API. Identifying this as early as possible helps ensure you are architecting a compliant solution that meets the needs to all factions of the enterprise.
Considering the value of contracts also helps ensure your architecture is setting the organization up for effective development of different parts of the API across different teams in the organization. You may have a complex API which requires engagement from multiple teams, including, outsourced vendors. While it’s important that these different teams communicate and work collaboratively, the reality is that these different teams may be working within completely different statements of work (SoW). Agreeing on a contract for your API as early on in the SDLC process as possible will establish very detailed scopes of work for different development teams.
With established contracts, your testing teams can start writing test scenarios early on in the development process and can validate their tests once the API is functional. Your contract will allow you to mock up your API before the API development is complete which will allow other teams working on APIs that consume other APIs to use the mocked versions of those APIs as part of iterative API development. Once the subsequent APIs are ready for prime time, the mock can be easily switched out for the real thing.
In conclusion, the importance of API contracts cannot be overlooked as an integral component of the underlying architecture. The solution needs to take into account all of the governance constraints of the enterprise and defined contracts can help ensure that governance concerns are identified and requirements are met. Contracts help the underlying solution lend itself to effective iterative development and testing while allowing multiple teams across the enterprise, working within different scopes of work, the ability to work uncoupled, if needed, from the rest of the solution team. Ultimately, the solution architect is going to be responsible, holistically, for the entire solution, but ultimately, your CISO, has the unbridled capability to prevent the solution from even going into production if you screw it up. Contracts, as an integral part of the architecture, aid in the cadence of iterative solution development and help ensure that the appropriate governance requirements are identified and implemented as early as possible in the SDLC.