API Gateway is the AWS service customers use to build, secure, and manage their own APIs, but it offered no way to publish those APIs so other people could discover them, read their documentation, and test them. It had been one of the most requested capabilities from customers for years: an integrated developer portal where they could publish and govern their APIs directly, without standing up separate infrastructure themselves. That gap had persisted while prior years went toward operational fixes to the core API Gateway service, leaving no room to invest in a new capability like this one. Competitors weren't waiting: IBM's API Connect, for example, already bundled a developer portal directly into its platform alongside API lifecycle management and gateway capabilities. Customer pressure built in the meantime: without a portal, customers turned to third-party services or built their own, taking on the infrastructure cost and resourcing burden themselves. Internally, that same gap showed up as multiple teams building near-duplicate portal solutions for the same underlying problem, often without a consistent set of API standards behind them. The gap carried competitive weight too: the 2025 Gartner Magic Quadrant for API Management placed AWS as a Challenger, and this was a key offering standing in the way of Leader status.
The portal closed both sides of that gap at once: providers could finally publish and govern their APIs, and consumers could discover, review documentation for, and test them directly, all without providers standing up separate infrastructure.
Delivering that meant designing a two-sided experience essentially from scratch, one for providers and one for consumers, while integrating cleanly into a service with years of conventions customers already relied on.
Consumers can call a real endpoint directly from its documentation page, using their own credentials, and see the actual response before writing any integration code.
Portals contain products, which are a collection of endpoints.
Providers see and manage the portal's home page directly, with a live preview of what customers will see.
Consumers land on that same home page, ready to browse products and start exploring the API documentation.
Setting up a new portal was a complex, multi-step operation. We simplified it into three steps: define the portal's details, select which products to include, and customize its design with a live preview.
The service needed a two-sided experience: one side for providers publishing and managing their APIs, another for consumers discovering and testing them. Both had to integrate cleanly into years of existing experience decisions already built into API Gateway, some of it carrying rough edges of its own. That meant working within a web of intertwined experience constructs already familiar to existing customers, tying the new service to them seamlessly while making decisions that would set the team up for what came next rather than boxing us in.
Much of the complexity came from how flexible the product needed to be. Providers needed to group endpoints from different APIs together into a single product, regardless of which underlying API each endpoint came from. View permissions needed to reflect account-level access: what someone could see or manage in the portal had to line up with what they already had access to elsewhere in AWS. Providers also needed the ability to share specific endpoints from their APIs with a portal creator without handing over the whole API, and documentation needed to be tailored differently depending on who was viewing it. Each requirement was reasonable on its own; together, they multiplied the number of states and permutations the design had to account for.
Design needed to be complete in five months, working backwards from the security reviews and release management process required ahead of a major launch at AWS's annual re:Invent conference. In that window, we had to deliver a service that let providers publish and govern access to their APIs, and let consumers discover, review documentation for, and test them directly, all without providers standing up separate infrastructure. That meant building automatic discovery of a customer's existing APIs across accounts, reconciling years of existing documentation from APIs that had either been created natively in API Gateway or imported into it, and building access controls providers could enforce out of the box. Any one of these would have been a meaningful project on its own; building all of them together, on a compressed timeline, meant the design had to get the underlying model right the first time.
Developers can browse a product's full set of endpoints and read the documentation behind each one before they build against it.
The lead designer on my team ran feedback sessions with AWS solutions architects, support engineers, and delivery consultants, customer-adjacent roles used as a proxy for external customers ahead of launch. I helped shape what we needed to learn going in. The sessions surfaced a real risk: the resource model underlying the portal (Endpoints, Products, and Portals) didn't match how customers already thought about their APIs, and no standard for organizing APIs existed in the marketplace to anchor the concept to. Rather than change the model this late in the timeline, we accepted it wouldn't be obvious at first glance and relied on the product creation experience itself to teach it through use.
We built confidence in that approach through more than 25 follow-up customer calls, including early adopters, who confirmed the model became clear once they'd used it.
Preview was part of the experience, but it could take minutes to load each time it was called. The team's original plan was to generate previews using real infrastructure. I pushed the team to find something faster, and asked them to look at leveraging the customer's own local device instead of provisioning backend infrastructure for every preview. They found a way to do it: because the provider had already loaded their own API and product data into the browser, the preview could render that data locally and instantly, without an additional call to live infrastructure.
The initial design offered only a full-scale preview, separate from where a provider was actually editing. I pushed the team to also embed parts of the preview directly next to the content being edited, making changes easier to see in context alongside the full-scale option. The lead designer was struggling to work through how to structure both views together without overcomplicating the screen. I ran a pairing session with him where we worked through a number of concepts together. Within an hour, we'd settled on an approach that resolved a debate that had been open for weeks.
Editing the portal's navigation, adding and organizing pages in its nav bar, needed a pattern that didn't exist yet in Cloudscape, AWS's internal design system. The lead designer worked directly with the Cloudscape design team to develop one. I connected him with the right people there, and the team finalized a solution in two weeks, a process that can normally take months to get through design system standardization and acceptance.
Providers already had API documentation living in the main API Gateway console, and the portal introduced a second, consumer-facing copy of that documentation. The original design linked out to the API Gateway console to edit it, pulling providers out of the product creation flow they were already in. I pushed early on for a different concept: view the existing documentation in place, with the ability to customize it, without leaving the portal experience. It wasn't readily adopted at first. The team's instinct was that providers would want to update both copies together, and there was a concern that documentation needed to be fully published before it could be part of the portal experience at all.
I pushed to separate the two. The primary task in product creation was getting a published version of documentation ready for the portal, distinct from the documentation tied to the API itself. If a provider wanted to update the canonical, endpoint-level documentation, they could still do that in the API Gateway console. The portal defaulted its documentation to whatever existed at the endpoint level, with the option to override it in place for the portal, and providers could toggle between the two to see exactly what would change before publishing.
Product creation started as a five-step flow that asked providers to take in too much at once. Working with the lead designer, we brought it down to three steps, including review. The second step let providers view every API available to them, drill into a specific one, and select specific or all endpoints to include in the new product. The third step was a review before creating the product.
Customer feedback flagged that it wasn't clear which products were available from outside the account a provider was currently working in, a common scenario for large organizations running many AWS accounts. We labeled those products as shared, showed which accounts had access, and extended that visibility through AWS Resource Access Manager (RAM).
Providers group their API endpoints into products, then customize how each one appears and is documented in the portal. A single product can belong to one or more portals, so a provider only has to define it once and reuse it anywhere it's shared.
This new service unblocked API Gateway to become an industry leader. The portal removed one of the gaps standing between AWS's Challenger position and Leader status in the 2025 Gartner Magic Quadrant for API Management, closing a capability customers had been asking for directly.
Customers no longer need to build and host their own infrastructure to publish documentation, let consumers discover their APIs, or support in-browser testing. That work, and the ongoing maintenance it required, moved into a managed AWS capability.
A shared portal gave teams a central place to see what APIs already existed, reducing the chance of building a near-duplicate developer portal for something that already had one elsewhere in the organization. It also gave API Gateway a consistent way to enforce documentation quality and access governance across an organization's APIs, standardizing something that had previously been left to each team's own approach.
The feature shipped publicly in November 2025 as Amazon API Gateway Portals. Adoption moved faster than the team expected, with XL enterprise customers making up a disproportionate share of early adopters. The service has shown consistent month-over-month growth since launch, alongside new customer acquisition.
