Publishing an API Portal

About this paper

I have been telling people to publish a developer portal for sixteen years, and this paper opens with the thing the portal vendors never will: the portal is not your API, and it is not your product. It is the human-readable front door to an operation you should already be running — and it is the most honest artifact your company publishes, because a stranger can evaluate it in ninety seconds without ever talking to you. Your portal is a mirror of your organization.

The paper places you in one of three portal archetypes — public/open, partner/gated, or internal — then walks the full anatomy of a front door: overview and getting-started, reference and conceptual docs, self-service authentication, interactive consoles and sandboxes, SDKs and samples, plans and pricing and rate limits, support and community, status and changelog and deprecation — all generated from a single source of truth so they cannot drift. It covers meeting developers where they actually work (the IDE, the terminal, the package manager), the anti-patterns I watch for, and the agentic turn where the portal grows a second, machine audience that enumerates capabilities instead of reading pages. You get a provider self-assessment you can run in an afternoon.

What's inside

1. The portal is not the API — and what it actually is
2. Locate yourself — the three portal archetypes
3. Do you even need a portal?
4. The anatomy of a portal, generated from one source of truth
5. Meet your consumers where they already are
6. The portal is operations, not a launch
7. Anti-patterns I'll be watching for
8. Where this is going — the portal's second audience
9. Provider self-assessment

What you get for $25.00