AppJoy Insights

Contract-first APIs: one OpenAPI file for Go and Flutter

In WhatDaFit, HoldMyBeer and Grifas, the API is written down once, in an OpenAPI file called swagger.yml. The Go server and the Dart client are both generated from it. This is the workflow, and why it saves time on every change. It also lets an app team and a backend team, even at different companies, work in parallel.

October 25, 2026 · By Tobias Wimmer, AppJoy

The workflow

Describe endpoints, request bodies, responses and errors in swagger.yml.
Run one command. go-swagger generates the Go server stubs and models, and openapi-generator generates the Dart client with dio and built_value.
Implement the handlers in Go on top of GORM and PostgreSQL. The Flutter app calls typed Dart methods instead of hand-written HTTP code.

Why it pays off

Backend and app cannot drift apart: a changed field is a compile error on both sides, not a bug found in production.
Less boilerplate: serialisation, validation and routing are generated.
The spec doubles as documentation for you and for any other developer who joins later.
The client is replaceable: a second app, a web client or a partner integration can use the same contract.

When client and server come from different teams

The approach pays off most when the app and the backend are built by different parties, for example the app by AppJoy and the backend by the customer or another vendor. Both sides agree on the OpenAPI spec first, and it becomes the contract between them.

Agree on the spec as early as possible, ideally in the first week, and treat changes to it like changes to a contract: both sides review them before they go in.

Work in parallel: the app team does not wait for the backend. Both start on day one from the same spec.
Mock the endpoints: a mock server, for example one generated from the spec, answers requests with the example responses defined in it. The app can be built and tested against realistic data before the real backend exists.
Plug it together at the end: when the backend is ready, the app switches from the mock to the real server, often by changing one base URL. If both sides followed the spec, it works as before.
Fewer misunderstandings: field names, types, error cases and authentication are written down, so there is less back-and-forth between the vendors.
Visible changes: a change to the spec shows up as a diff that both sides can review before anything breaks.

Deployment

The Go server compiles to a single binary. We deploy it to a Linux server, where it runs as a system service next to PostgreSQL. There is no container orchestration to maintain for a typical MVP.

Frequently asked questions

What is contract-first API development?

You write the API specification first, for example in OpenAPI, and generate code from it, instead of writing code first and documenting it afterwards.

Why Go for the backend?

Go is fast, simple to deploy as one binary and easy to maintain, which suits MVPs that need to grow.

Can the app be built before the backend exists?

Yes. With an agreed OpenAPI spec, the endpoints can be mocked from the example responses in the spec. The app is built and tested against the mock, and plugged into the real backend at the end.

What if the backend is built by the customer or another vendor?

Agree on the OpenAPI spec together at the start. Then both teams work in parallel against the same contract and integrate when both are ready, with far fewer surprises than without a spec.

Does this work with an existing backend?

Yes. If your backend has or can get an OpenAPI description, we generate the Flutter client from it. caberQU's app, for example, talks to a PHP API run by the client.

Case studies: WhatDaFit · HoldMyBeer · Grifas

Tell us about your idea

Describe your project in a few sentences. You get an estimate based on your idea.