OpenAPI & API Design

Interfaces that are defined before the first line of code – and that partners can integrate without follow-up questions.

dectria designs interfaces with OpenAPI and mostly works spec-first: the specification is written before the code and is the shared contract for frontend, backend and integration partners.

From the specification, we generate type-safe clients for the frontend and interfaces for the backend. Redocly presents it as readable documentation that partners can use from day one.

For existing interfaces without documentation, we create the specification afterwards and check it automatically against the running API.

Official website

Your contact Michael Jauk Contact for backend & architecture

What is OpenAPI – and when is it worth it?

OpenAPI is an open standard for describing REST interfaces in a machine-readable way: endpoints, parameters, data formats and errors. Documentation, clients, tests and mock servers can be generated from an OpenAPI specification. Its former name is Swagger.

OpenAPI is worth it as soon as more than one team or an external partner uses an interface. Spec-first is less worth it for internal endpoints that serve a single interface and change daily – a description generated from the code is enough there.

Spec-first or code-first?

	Spec-first	Code-first
Source of truth	the OpenAPI specification	the code; the specification is generated from it
Parallel work	frontend, backend and partners start at the same time	the frontend waits for the backend
Alignment	before implementation, based on the specification	after implementation, based on the code
Suited for	interfaces for partners and several teams	internal endpoints for a single interface

What We Build with OpenAPI / Swagger

API-First & Spec-First Design OpenAPI 3.x Specifications Documentation with Redocly Type-Safe Code Generation Client SDKs for Partners API Versioning Schema Validation Mock Servers Automated Tests Against the Specification Documenting Existing APIs

Use Cases

Typical Use Cases

Interfaces for Integration Partners

Partners receive the specification and documentation before the API is finished and can build their integration in parallel.

Developing Frontend and Backend in Parallel

The frontend works against a mock server generated from the specification while the backend is being built.

Documenting Existing APIs

Undocumented interfaces get a specification that is automatically checked against the running API.

References

Selected Projects

Web Application

Klanglicht - Art Festival of Bühnen Graz

Klanglicht Audio Guide

Mobile App

Radio Soundportal

Soundportal App

Web Application

Österreichische Raiffeisen-Sicherungseinrichtung eGen (ÖRS)

Deposit Insurance Payout Platform

View all references

FAQ

OpenAPI / Swagger FAQ

Why does dectria work spec-first?

Because the contract is fixed before code is written. Frontend, backend and partners can work in parallel, misunderstandings surface during alignment instead of after implementation, and documentation is available from day one. For purely internal endpoints, we also work code-first.

How does the specification become code?

From the OpenAPI specification, we generate type-safe clients for the frontend and interfaces for the backend, for example in NestJS. Every API change starts with a change to the specification. Automated tests check that the running API matches the specification.

Can dectria document existing APIs?

Yes. We analyze the existing endpoints, create an OpenAPI specification from them and set up automated checks so the documentation stays current. This is often the first step of a modernization.

How do API changes stay backward compatible?

We add new fields and endpoints without changing or removing existing ones. Unavoidable breaking changes go into a new version, and the old one remains available for an announced transition period. Automated comparisons of the specification show before each release whether a change would break clients.

Every project starts with a conversation.

Let us talk about your individual needs and goals.

Start a project