Contract-First APIs

Role: Frontend Engineer, leading architecture for frontend infrastructure and applications
Outcome: Shared API contracts and generated SDKs adopted across multiple services
Focus period: 2024–2025

Overview

Stockholm Exergi’s product suite depends on consistent data and reliable integrations between backend services and frontend applications. By 2024, we needed a faster, safer way to evolve APIs without introducing breaking changes or duplicated client code across teams.

I led the frontend architecture for a contract-first approach: backend and frontend defined the API contract together, used that contract as the source of truth, and generated type-safe SDKs and query hooks directly from it.

The Challenge

We needed to reduce integration risk while increasing delivery speed across multiple services.

  • API changes were costly to coordinate across teams
  • Frontend integrations required repeated manual setup
  • Validation logic drifted between backend and frontend
  • Onboarding new engineers meant re-learning API patterns

The Approach

We aligned on contract-first API design. The contract defined the shape of every endpoint, request, and response. From there we automated everything we could.

Our workshops started from the UI. We brought user flows and rough mock-ups, walked through the screens together, and mapped the data structures needed to power each state. We defined the exact endpoints and methods required to create, update, and delete content before any implementation started.

After the contract was agreed, teams could split and move fast. Frontend generated SDKs and mock APIs from the contract, while backend implemented the real services. When the mock switched to production, it worked because both sides had built to the same contract.

  • Co-authored OpenAPI specs with backend engineers during design reviews
  • Used the contract as the single source of truth for API behavior
  • Generated TypeScript SDKs with Kubb
  • Generated TanStack Query hooks for consistent data access patterns
  • Generated Zod validators to keep client-side validation aligned

Implementation Highlights

We rolled the system across more than four services, with additional services in the pipeline when I left.

Contract workflow
Backend and frontend defined contracts together in Stoplight (SmartBear). The visual editor let us build OpenAPI specs without hand-writing YAML, while enforcing shared endpoint rules from our best-practices guidelines. The OpenAPI spec was treated as a required artifact for every API change.

Generated SDKs
Kubb generated a typed SDK for each service, producing request/response types, API clients, and hooks. This eliminated hand-written API client code and reduced drift between contract and usage.

Frontend integration
TanStack Query hooks standardized loading, caching, and error handling. Zod validators provided runtime safety for incoming and outgoing payloads, so posted data matched the contract as strictly as responses.

Results

The system reduced integration friction across teams, made API changes safer to roll out, and shortened the feedback loop between backend and frontend development.

  • Faster onboarding: one consistent API pattern across services
  • Fewer contract mismatches: types and validators generated from the same source
  • More predictable delivery: API changes were reviewed against a shared spec

Learnings

Contracts are collaboration tools.
The biggest win was not just type safety—it was shared ownership. Writing the contract together aligned backend and frontend early, before code diverged.

Generated clients free teams to focus on product work.
Once the SDKs were in place, teams stopped rebuilding API integrations and moved faster with fewer regressions.

Technical Summary

Stack: TypeScript, OpenAPI, Kubb, TanStack Query, Zod, React, Vite

Scope: Applied across 4+ backend services, with additional services queued at the time of handover

Lets connect if you want to build reliable, scalable API contracts and type-safe frontend integrations that reduce bug tickets and increase delivery speed.