API Contracts with OAS
What is OAS or the Open API Specification?
I mentioned before how an API-First pattern requires a mindshift: It requires architects and developers to think about the specification first, and adopt a domain driven design approach when building them at scale.
That helps consolidating and enforcing a style across multiple teams, even when they don’t communicate with each other in any other way than accessing the contract.
The OAS itself is a document pushed to the repo where the API lives in, written in a machine readable format -typically JSON or yaml-, in a file called openapi.* so it can be discovered and read by both other developers or systems, to understand how to maintain and interact with the API.
Check TypeSpec a tool to generate OAS from code very similar to TypeScript! It’s a protocol agnostic language to describe API shapes.