04. Follow API-First practices

Date: 2024-12-10

Status

Accepted

Context

We want to ensure we have a development practice where we always produce well-documented and thoroughly reviewed API specifications.

Decision

We have decided to implement the API-First approach. This means that implementation starts from the schema or specification. We also craft schemas by hand and author them in proto syntax. We will not use schema generators to produce any of our schemas from Java sources.

Consequences

Developers will need to know how to craft specifications, meaning they need to understand proto3 specifications. In the team, we need to ensure everyone knows which IDEs and plugins offer the best support for schema design and previews.