Agree on the API before you build the apps

This week I've been working on a project with several mobile apps. The apps are dumb on purpose. They don't do anything on their own, except in offline mode. Everything they show and everything they change goes through an API on our Rails server.

It's gone slower than anything else I've worked on lately, and it took me a few days to see why.

Everything waited on something else

In past weeks, most of my work could be built in parallel. I'd plan a few pull requests, start them all, and they'd come back around the same time. I've written about running that in parallel and giving each pull request its own session.

This project didn't work like that. Every step went the same way:

Build or change an endpoint in Rails.
Ship it.
Then build the screen that uses it, in each app.

The apps couldn't start until the server was done, because nobody knew exactly what the server would return. And when feedback came in mid-week asking for more than the original design had, it started the chain over again: Rails first, then every app.

So the work happened one link at a time. Having more agents didn't help, because each one would have been waiting on the one in front of it.

Agree on the contract first

I was talking about this with our CTO today, and he had a really good suggestion. For a project like this, with one server change and a bunch of client changes, start by agreeing on the shared interface. Write down what the API will look like before anyone builds it, as a contract between the server and every client.

Then everyone builds to the contract at the same time:

The server implements the endpoints so they return exactly what the contract says.
Each app builds its screens against the contract, using fake responses until the real server is ready.
At the end, you connect them and fix whatever doesn't line up.

The apps stop depending on the server being finished. They only depend on the contract being agreed, and that's a much smaller thing to wait for. Instead of server, then app, then app, then app, you get one short step of agreeing, then everything at once.

There's still some integration work at the end. But integration is a lot cheaper than waiting.

Writing it down

There's a standard way to write an API contract: an OpenAPI spec (what used to be called Swagger). It's a file that lists every endpoint, what it takes, and what it returns. A spec like that is useful for more than this project:

It's the API documentation, so the contract doesn't become a stale doc nobody reads.
The server's tests can check that the real responses match the spec.
The apps can generate fake responses from it, so they're never blocked on a running server.

The spec matters more when agents are doing the building. An agent working on one of the apps can't lean over and ask the server agent what a field is called. With a spec, it doesn't have to: the answer is in the file.

What I'll do next time

If I work on a project like this again, the first piece of work won't be code. It'll be the contract:

Map every screen in every app to the data it needs.
Write the API that serves that data as a spec, before building any of it.
Review the spec with whoever owns each client, and agree on it.
Build the server and every app in parallel, each against the spec.
Connect them and fix what doesn't match.

Changes will still happen. When they do, they start with the spec, and everyone builds from the new version.

I think this would have made this week go a lot faster. The work wasn't hard. It was just stuck in a line, and the line was there because nobody had written down what we were agreeing to.