APIs as a Product, Part 4 of 10 · The first hour decides the relationship.
Picture how partner onboarding often starts without a developer portal. A kickoff call. A PDF of the API. A sandbox key sent by email. Then a week of waiting, until the partner's developer comes back with a list of questions, most of which the PDF could have answered if it had been written for them rather than for the team that built the API.
That setup measures the wrong moment. It cares about the day a partner goes live. But the partner's developer has already made up their mind much earlier: in the first hour, when they try to understand what the API does and whether they can get something working before lunch.
Developer experience is mostly decided before the first request is sent.
The journey before the call
When I worked on the open API and developer portal at Delivery Hero, we mapped the partner journey as four stages: spec, sandbox, certification and go-live. Each stage had its own way of losing people.
At the spec stage, developers lose interest when the docs describe endpoints instead of jobs. Nobody arrives wanting to call an endpoint. They arrive wanting to send an order, update a menu or check whether a payment went through. So we organised the docs around those jobs, and kept the endpoint reference underneath for when they needed it. The contract itself was written first, as an OpenAPI spec, so the docs, the mocks and the code all came from the same source.
At the sandbox stage, developers lose trust when the sandbox is nicer than production. A sandbox that always returns success teaches a partner nothing. Ours needed to fail the way production fails: a merchant closed, an item out of stock, a payment declined, a timeout. A partner who has handled those in the sandbox doesn't page you at 2am in their first week live.
Certification used to be a meeting. We read a checklist aloud, the partner said yes to each line, and we switched them on. Then one of them failed on the first closed merchant in production, because "yes" in a meeting is not the same as code that handles it. After that we turned certification into a checklist partners ran against themselves: the calls they had to make, the failure cases they had to handle, the webhooks they had to verify. It moved certification from a meeting into a test.
Go-live was the easy part by then. That was the point.
The number that told us the truth
The measure that changed how we worked was time to first successful call: how long from getting access to getting a real, correct response back. It's a blunt number, but it captures everything above. Confusing docs, a broken key, an unclear error message: they all show up as time. Alongside time to go-live, it was the number we ran the portal by, and partner onboarding went from weeks to days.
Error messages turned out to matter more than almost anything else in the docs. A developer will read a page of documentation once. They will read your error responses every day. "400 Bad Request" tells them nothing. An error that names the menu item and the merchant it couldn't find tells them what to fix without opening a ticket.
A developer portal is not a website with documentation on it. It's the first hour of a relationship, and most partners decide in that hour whether the rest will be worth the effort.