API First in Practice: How We Made Frontend Types Predictable and Stable

The Problem: Frontend–Backend Desynchronization

Frontend and backend teams often develop in parallel, leading to inconsistencies and bugs that surface late in the development cycle. A common issue is outdated frontend TypeScript types due to API changes, resulting in runtime errors and production issues.

Why This Matters

Ideal software development assumes seamless communication and synchronization between teams, but in reality, discrepancies inevitably occur. Manual maintenance of TypeScript types doesn’t scale, and even with good communication, frontend teams often discover breaking API changes too late, leading to costly bug fixes and delayed releases.

Key Insights

• openapi-generator: A tool used to generate TypeScript code from OpenAPI schemas.
• OpenAPI as a Contract: Treating the OpenAPI schema as the single source of truth for the API, rather than just documentation.
• CI Integration: Using Continuous Integration to automatically validate the generated types and catch breaking changes early.

Working Example

openapi: 3.0.3
info:
title: User Service API
description: API for managing users
version: "1.0"
paths:
/users:
get:
tags:
- users
summary: Get list of users
operationId: listUsers
responses:
"200":
description: List of users
content:
application/json:
schema:
$ref: "#/components/schemas/UserListResponse"

export const UserStatusEnum = {
Active: 'active',
Inactive: 'inactive',
} as const;
export type UserStatusEnum =
typeof UserStatusEnum[keyof typeof UserStatusEnum];

Practical Applications

• Stripe: Uses generated client libraries to ensure consistent API interactions across their frontend and backend systems.
• Pitfall: Manually overriding generated types can reintroduce inconsistencies and defeat the purpose of the API First approach.

References:

• https://dev.to/dmitrii-verbetchii/api-first-in-practice-how-we-made-frontend-types-predictable-and-stable-332c