Apiboost: From Requirements to Launch for a Multi-Gateway Developer Portal
How Business Analysis Canada led requirements for Apiboost's multi-gateway developer portal, then carried design, development, SEO and support.
- 3+ gateways behind one portal, including Apigee, Azure and AWS
- 4 requirement areas: catalog, documentation, access and onboarding
- ~4 months of analysis and design before development started
- ~8 months of development to the first release
Project at a glance
- Client
Apiboost, a developer-portal product spun out of Achieve Internet. It sits above the gateway layer, so enterprises can publish, govern and onboard developers across Apigee, Azure API Management, AWS API Gateway and other gateways without tying the developer experience to one vendor. - Engagement
Analysis-led, end-to-end delivery. We built a validated requirements baseline first, then carried it through design, software development, search engine optimization and project support. - Duration
About 4 months of analysis and design, about 8 months of development to the first release, then ongoing project support - Our role
Business Analysis Canada led the analysis and carried the work through every later phase. - Scope
Requirements for the API catalog, documentation, access and onboarding; portal journey models; interface design and page structure; development against the validated requirements; SEO for public pages; and project support
The challenge
What problem was the client trying to solve?
Large organizations rarely run all their APIs on one gateway. Apiboost needed a portal that gives developers one consistent experience, whatever runs underneath.
- Too many portals
Enterprises often run several gateways, after acquisitions, cloud migrations or different team choices. Each gateway has a separate portal, so developers deal with several logins, catalogs and onboarding processes. - No common model
Each gateway models API products, consumer apps, credentials and quotas differently. A portal spanning them needs one consistent model on top, with clear rules about which system is responsible for what. - Enterprise governance
Enterprise buyers expect governance: who can see which APIs, who approves access, how credentials are issued and revoked, and what gets logged. - First minutes count
Developers judge a portal in minutes. If they cannot find an API, understand it and get credentials quickly, they move on. - Findable public pages
The product had to be found as well as used. Public API pages and product pages needed to be visible to search engines, not hidden behind logins. - No agreed baseline
Stakeholders had many ideas for the roadmap. The team needed an agreed baseline before design and build, so every new idea could be judged against it.
Our business analysis approach
How did we approach the engagement?
How did we build the requirements baseline?
We completed and signed off the analysis before any design or development started, so every later phase had the same reference point.
- Stakeholder mapping
We identified stakeholders across Apiboost's product leadership, Achieve Internet's solution architects, sales and customer success, and enterprise customer representatives such as API platform leads, API product managers and security reviewers. A RACI matrix defined who contributed to, reviewed and signed off each requirement area. - Elicitation
We ran interviews and workshops with API publishers and platform teams, interviewed developers and observed them completing tasks on existing portals, reviewed competing developer portals, and studied each gateway's management APIs and sample OpenAPI specifications. - Personas
We defined personas for API consumers (external, partner and internal developers), API publishers (API product managers and technical writers), governance roles (platform leads and security reviewers) and portal administrators. - Portal journey modelling
We mapped the consumer journey from discovering and evaluating an API to trying it, registering, requesting access, receiving credentials, going live and monitoring usage. We also mapped the publisher journey from syncing an API from the gateway to enriching, publishing, versioning, deprecating and retiring it, and the administrator journey for SSO, roles, approval workflows and branding. Steps with approvals and handoffs were modelled in BPMN. - Common model and gateway mapping
We defined one set of portal concepts and mapped each one to the equivalent object in every supported gateway. We also agreed which system is the record for each concept. - Business requirements document
The BRD covered objectives, scope and exclusions, business rules, assumptions, constraints, dependencies and success criteria for the catalog, documentation, access and onboarding. - Acceptance criteria
Every requirement received Given/When/Then acceptance criteria, validated with Apiboost's product team and customer representatives. - Non-functional requirements
We set requirements for security (SSO through SAML and OpenID Connect, role-based access, audit logs, protection against common web vulnerabilities), performance of search and documentation pages, availability, multilingual content, accessibility to WCAG 2.1 AA, white-label theming and SEO. - Baseline sign-off
Apiboost signed off the baseline before design started. It was version-controlled, and every later change was measured against it.
Gateway mapping
How did one portal map to different gateways?
The hardest analysis problem was making different gateways look the same to a developer. The table shows the simplified mapping behind the portal's common model.
Portal concept
Apigee
Azure API Management
AWS API Gateway
API bundle offered to developers
API product
Product
Usage plan with API stages
Consumer application
Developer app
Subscription
API key linked to a usage plan
Credentials
Consumer key and secret
Primary and secondary subscription keys
API key
Team or organization
AppGroup (company in Apigee Edge)
Group
Managed in the portal
Quotas and rate limits
Quota settings on the API product
Rate limit and quota policies on the product
Usage plan throttling and quota
We also agreed which system is responsible for what, to prevent sync conflicts:
- The gateway is responsible for runtime enforcement, credentials, quotas and traffic.
- The portal is responsible for catalog content, documentation, visibility rules, teams, access approvals and terms-of-use acceptance.
- Credentials are created in the gateway through its management API, only after the portal's approval workflow allows it.
Acceptance criteria
What did the acceptance criteria look like?
Acceptance criteria covered the four areas the business validated: catalog, documentation, access and onboarding. One example for each:
Catalog visibility
- Given an API is marked as partner-only
- When an anonymous visitor searches the catalog
- Then the API does not appear in the results
- And its pages are excluded from search engine indexing
Documentation versioning
- Given an API has versions 1 and 2 published
- And version 1 is marked as deprecated
- When a developer opens the version 1 reference
- Then a deprecation notice shows the retirement date
- And links to the version 2 reference
Access approval
- Given an API product requires approval for production access
- When a developer requests production access for their app
- Then the request goes to the approval queue for that API
- And no production credentials are issued until it is approved
- And the developer is notified of the decision
Onboarding
- Given a new developer has registered and verified their email
- When they create their first app
- Then sandbox credentials are issued automatically for self-service APIs
- And the getting-started guide shows a sample request using those credentials
Design
How did design follow the baseline?
Design turned the validated journeys into the portal interface and page structure, without adding scope outside change control.
Information architecture
We defined the page structure: home, API catalog, API overview, reference documentation, guides, changelog, app dashboard, team management, account settings and support. Navigation was checked with developers through tree testing.
Wireframes to final designs
Wireframes for each page type were reviewed against the acceptance criteria, then developed into high-fidelity designs.
Component library
Reusable components covered API cards, endpoint reference layouts, code samples, a try-it console, and lifecycle badges for beta, generally available and deprecated APIs.
White-label theming
Enterprises can apply their logo, colours and typography. Theme settings include contrast checks so customer branding cannot break accessibility.
Usability testing
Developers completed realistic tasks on prototypes, such as finding an API for a given purpose, getting credentials and making a first call. Findings went into the design before development.
Development
How did development implement the requirements?
Development worked from the same baseline, so each feature could be traced back to a requirement the business had validated.
Backlog from the baseline
Epics and user stories were derived from the BRD and linked to requirements, journeys and designs. A story was ready for development only when it had acceptance criteria and an approved design.
Gateway connectors
A connector for each gateway implemented the common model: importing and syncing OpenAPI specifications, mapping products and apps, and creating and revoking credentials through each gateway's management API.
Governance features
Development covered visibility rules, approval workflows, teams, role-based access, SSO, terms-of-use acceptance and audit logging, all as specified in the baseline.
Search and documentation
Catalog search with filters for domain, tag, gateway, version and lifecycle status, plus rendered reference documentation, guides and changelogs.
Testing
Acceptance tests came from the criteria. Integration tests ran against sandbox instances of each gateway, alongside security, accessibility and performance testing.
Releases
Changes moved through automated build and deployment pipelines into test and production environments.
SEO
How did SEO make the product findable?
Many developer portals render documentation only in the browser and hide it behind logins, so search engines never see it. SEO requirements were part of the baseline, not added after launch.
Indexing rules
Public catalog and documentation pages are indexable. Partner-only, private and logged-in pages are set to noindex and left out of sitemaps.
Crawlable documentation
Public reference pages are rendered on the server, so search engines can read the content.
URL and version structure
Each API and version has a clean, stable URL. Canonical tags point older versions to the current one where the content overlaps.
Metadata templates
Titles and descriptions for API pages are generated from each API's name and summary, with manual overrides for key pages.
Structured data
Product pages use software application markup, and documentation pages use API reference markup.
Product pages
Keyword research shaped the public product pages around terms such as multi-gateway developer portal and API developer portal.
Measurement
Search Console was set up from launch to monitor indexing, coverage and search queries.
Project support
How did project support keep delivery aligned?
Requirements kept changing after the baseline. Project support made sure each change was assessed and decided, not slipped in.
Change control
Each new idea was assessed against the baseline for its effect on design, connectors, tests and timeline, then approved, rejected or parked by Apiboost's product team.
Gateway changes
We monitored vendor updates to the gateways' management APIs, assessed their impact on the connectors, and ran regression tests before each release.
Defect triage
Issues were checked against the acceptance criteria. If the build did not meet a criterion, the issue was a defect. If it met the criteria but different behaviour was wanted, it became an enhancement request.
Living documentation
The BRD, journey models, gateway mapping and acceptance criteria were updated with every approved change, and release notes were prepared for each release.
Traceability
How did we keep everything traceable?
- A requirements traceability matrix linked each requirement to its journey, design, user stories, test cases and release.
- The baseline was versioned, and every change request recorded what changed, why, and who approved it.
- A decision log captured product decisions, including the system-of-record rules for each gateway.
- Apiboost's product team signed off the baseline, the designs and every release.
Which BA techniques and tools did we use?
Techniques
- Stakeholder mapping
- RACI
- Interviews and workshops
- Task observation
- Competitive analysis
- Personas
- Journey mapping
- BPMN process modelling
- Common data model design
- System-of-record analysis
- BRD authoring
- Given/When/Then acceptance criteria
- Non-functional requirements
- Information architecture
- Tree testing
- Wireframing
- Usability testing
- Requirements traceability
- Change control
- Technical SEO audit
- Keyword research
Tools
- Jira
- Confluence
- Figma
- Miro
- Postman
- Swagger Editor
- Google Search Console
- Screaming Frog
- Lighthouse
Results
What were the results?
- 3+ gateways behind one portal, including Apigee, Azure and AWS
- 4 requirement areas: catalog, documentation, access and onboarding
- ~4 months of analysis and design before development started
- ~8 months of development to the first release
One validated requirements baseline guiding design, development, SEO and support.
- A consistent developer experience across Apigee, Azure API Management, AWS API Gateway and other gateways, so developers do not need to know which gateway runs an API.
- Governance that enterprise buyers can test: visibility, approvals and the credential lifecycle defined in requirements and verified through acceptance tests.
- A self-service path from registration to sandbox credentials and a first API call.
- Public product and documentation pages that search engines can crawl and index.
- Scope changes handled through change control rather than added informally.
“
Lessons learned
What can other product teams learn from this project?
- Define the common model before building connectors. A multi-gateway product depends on how well it maps each vendor's concepts.
- Decide which system is responsible for each piece of data. When the portal and the gateway both manage the same data, sync conflicts follow.
- Write acceptance criteria for governance, not just features. Visibility and approval rules are what enterprise buyers test first.
- Plan SEO alongside the information architecture. Documentation that only renders in the browser will not be indexed.
- Measure developer experience across the whole journey, from first visit to first successful API call.
Planning a developer portal or API product?
Talk to a senior business analyst about setting a validated requirements baseline first, then carrying it through design, development, SEO and support.
Apiboost: From Requirements to Launch for a Multi-Gateway Developer Portal
