Developer Portals: A Self-Service Hub for APIs
A developer portal is a self-service hub for APIs, bundling docs and access controls so developers can discover and use APIs without platform team help. They're used externally for third-party developers or internally for infrastructure automation.
Why it exists
As an organization's API landscape grows, it becomes difficult to make those APIs discoverable, testable, and usable while maintaining consistent security and governance. A developer portal solves this by creating a centralized, structured hub that prevents API sprawl and knowledge silos.
The mental model
Think of a developer portal as a self-service storefront for your APIs. Instead of developers asking a platform team for access or information, they can browse a catalog, read the documentation, get their own keys (credentials), and track their usage, all in one place.
How it works
A developer portal is a developer-facing interface that exposes APIs with their documentation, authentication, access controls, and usage tracking. It enables developers to discover and consume APIs without direct platform team involvement. This is especially powerful for internal portals, which expose Infrastructure-as-Code (IaC) automation and allow teams to provision resources through a controlled, self-service workflow rather than by filing tickets.
When to use it
Use an external portal to expose product APIs to third-party developers, like Stripe or Twilio do. Use an internal portal to give your own development teams self-service access to infrastructure, cloud provisioning, or shared internal services. This reduces bottlenecks and dependency on a central platform team.
When not to use it
A portal is overkill for a small number of simple, internal-only APIs understood by a small team. If your only need is to route and manage API traffic without a developer discovery layer, an API Gateway by itself is the more appropriate tool. The portal is specifically for the developer experience layer on top.
One canonical example
An internal developer portal allows a new engineering team to provision its own staging environment. Instead of filing a ticket and waiting, the team logs into the portal, finds the "Staging Environment" API, authenticates via company SSO, and uses the provided interface to trigger an IaC automation that provisions all necessary cloud resources according to company standards.
Interview question
What is the primary functional distinction between a developer portal and an API Gateway?
- a.An API Gateway manages API documentation and access credentials, while a developer portal primarily monitors API performance.
- b.Developer portals are used for external APIs, whereas API Gateways are exclusively for internal microservices.
- c.A developer portal provides a self-service layer for API discovery and consumption, while an API Gateway focuses on traffic routing and policy enforcement.Correct
- d.A developer portal is essential for all API deployments, while an API Gateway is only needed for high-traffic scenarios.
Why? this is the answer
The card explicitly states that a developer portal is for the 'developer experience layer' including discovery and consumption, while an API Gateway is for 'route and manage API traffic without a developer discovery layer.' Option B is incorrect because portals are used for both internal and external APIs.
Just read this? Test yourself on what you have been reading.
Read the original → cycloid.io
- #api
- #platform engineering
- #developer experience
- #self-service
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on api — each one lists the topics its interview covers.
See open roles