Skip to content 2.0

API Contracts with OAS

Author: Natalia Venditto

Date First Published: Wed Jan 04 2023

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.