Treat the API as a product other companies build on, so stability and developer experience matter as much as features. Partners can't redeploy on your schedule, so a breaking change costs far more than in an internal API.
Put developer experience first. Give partners clear documentation and an interactive API explorer. Add SDKs in popular languages and a sandbox environment.
Pick an access model. Public APIs are open to all developers, partner APIs have restricted access, and private APIs are for internal use.
Make onboarding self-service. Partners register and manage their own API keys. They pick a usage tier with billing, and know which support channels to use.
Offer the integration patterns partners expect. Webhook notifications and polling endpoints cover most needs. Add real-time APIs over WebSockets for live data and batch processing APIs for bulk work. Partners subscribe to webhook events through an endpoint like this one.
Documentation: the docs come from the spec, not a hand-written copy
Hand-written docs are a second copy of what the code does, and copies go out of date. A spec that generates the reference, clients and checks cannot go out of date.
For this question · chapters 2 and 3 of 3This answer puts developer experience first for partners. Watch a mock server reply from the spec before your endpoint exists. Then watch a partner make a first working call with a self-service key and a sandbox, plus an example that runs and a clear error.
2/3One spec, many outputs
One spec, many outputs
There are two ways to get one OpenAPI file. Write the file first and generate the handlers from it, or annotate the handlers and generate the file from them. Both ways produce the same file: 14 paths and 9 schemas, with 22 examples and 11 error codes. Five outputs could come from that file, but today a person types every one of them.
The reference page is now an output of the spec file, so nobody types the page any more. Every path, field and example on the page comes from that file, so the page always matches the code. The difference from chapter one is in how the page is built. The page does not depend on anyone remembering to update it.
In chapter one, a renamed field broke the partner's integration. Here the same spec file generates client libraries in four languages. Nobody writes those libraries by hand. So a field renamed in the spec changes in all four libraries on the next release. A build step now handles the exact change that broke the partner's integration.
The examples in the spec file are enough for a mock server to answer requests. The mock server replies before the real endpoint exists. So your partner waits zero days and starts building on day one. The examples in a spec are also worth writing properly, because a server is going to return them.
At the edge, the schema refuses any request with a field the schema does not define. The schema returns a 400 that names that field. So the spec file has a new role: the document that describes the API now enforces the API. A document you can run cannot be wrong without anyone noticing.
Drift, where the code no longer matches the spec, now fails the build. In CI, contract tests use the spec file as the test fixture and check every response against the matching schema. So a handler that drops a field fails the build. Chapter one's bug would have failed the build on your machine the day the bug shipped, not nine days later in a stranger's ticket.
Generation from the spec stops here, and this is the honest half of the answer. People write why to call this endpoint and how auth works end to end. They also write what to do about each error, and migration notes for a breaking change. An integrator reads these four documents first. Generation removes drift, but it does not write the explanation.
Twenty minutes, or nine days
Time to the first working call is a number you can measure and use as a design target. The measurement starts when a partner opens your docs. The partner then has to get past five gates, steps that block the call until each one is done. On most APIs, the first gate is a form and a call back from sales.
A key the partner can make on their own saves three days at the first gate, getting access. The partner signs up, creates a sandbox key on the page and pastes it in, all in two minutes. The key is scoped, so it cannot touch real money. A key that needs a sales call costs those three days before anyone writes a line of code.
An example that runs is worth more than a page that describes one. At gate two, the request runs exactly as the partner pasted it, with real values and the partner's own key already in it. The answer is printed beside the request, and the whole step takes two minutes. Building the same call from prose spread over four pages takes most of a day, and the call comes out wrong.
Gate three, the error response, is the one interviewers are listening for. The partner's first call fails with a 422 that carries a code the partner can look up. The error also names the field, the broken rule and what to send instead, so the fix takes three minutes, with no support ticket. The error you return is documentation, and integrators read it more closely than any other page.
Gate four is a sandbox, a safe place for the partner to be wrong. The sandbox holds seeded accounts (test accounts set up in advance) and fake money. So the partner can send twenty bad requests before lunch and has nothing to apologise for. Without a sandbox, the partner has two choices: test against production, or wait two days for someone to make them an account.
Gate five is not about the first call at all, but about turning one working call into a system somebody will build a business on. That system needs published rate limits, a changelog and a deprecation policy with dates. The same system also needs signed webhooks and idempotency keys, so a retry cannot charge twice. After twenty minutes, the partner is live.
Chapter 2 · step 1 of 7
There are two ways to get one OpenAPI file. Write the file first and generate the handlers from it, or annotate the handlers and generate the file from them. Both ways produce the same file: 14 paths and 9 schemas, with 22 examples and 11 error codes. Five outputs could come from that file, but today a person types every one of them.
A hand-written page is a second copy that nothing in your pipeline reads. So the page goes wrong without any warning. The fix is one OpenAPI file that generates the reference, client libraries and mock server. Request validation and contract tests come from the same file, so drift between code and spec fails a build. People still write the guides, error remedies and migration notes. For third-party integrations, name your design target: the time from opening your docs to one working call.
I treat a third-party API as a product other companies build on, and because partners can't redeploy on my schedule, stability and developer experience matter as much as features.
So developer experience comes first, with clear docs, an interactive API explorer, SDKs in the popular languages, and a sandbox where partners can test safely.
I decide early whether the API is public, partner-only, or private, and I make onboarding self-service so partners manage their own keys, pick a usage tier, and know where to get support.
For integration patterns, webhooks and polling cover most needs, and I add WebSockets for live data and batch APIs for bulk work.
Partners subscribe to webhooks with a POST that sets their callback URL, the events they want like order.created, and a shared secret for checking each delivery.
The cost is that every endpoint and event I publish becomes a promise I have to keep, so I'd rather launch a smaller API and grow it than remove things later.
Weak answers to avoid
Designs it like an internal APINaming resources and verbs isn't the point. Partners are outside developers, so talk about stability, docs, SDKs, a sandbox, and self-service onboarding.
Treats breaking changes as cheapPartners ship on their own schedule, so a break can take their product down. Say how you avoid breaks, and how you version and give notice when you can't.
Webhooks with no secret or retriesWithout a signing secret partners can't tell your calls from forged ones, and without retries a missed event is gone. Name both.
Hand-issued keys, no access modelEmailing keys by hand doesn't scale past a few partners. Say whether the API is public, partner-only, or private, and how partners get their own keys and pick a tier.
Interview lens
Likely follow-ups, what you can say, and the weak answers to avoid.
