How azure/api-management-developer-portal works
Project type and purpose
• This is a full-stack, client-heavy, self-hosted “developer portal” for Azure API Management (APIM).
• It provides an admin/design UI, a runtime SPA for API consumers, and a publishing pipeline to push content to the APIM service.
File structure
• Top-level folders:
• src/ – portal front-end code (TypeScript, React, Knockout.js, CSS/SCSS)
• auth/, authentication/ – Azure AD/B2C auth logic
• clients/, services/ – MAPI (management API) clients and business logic
• persistence/ – blob/object storage abstractions
• publishing/ – build/publish plugins that package and push static assets and configuration
• themes/, styles/ – design assets for portal and website
• scripts.v2/, scripts.v3/ – CLI tooling for generation, deployment, media management
• .github/workflows/, .pipeline/ – CI/CD definitions
• Widget-based architecture: each component (APIs lists, operations, users, reports, etc.) has design.publish.runtime modules, model-binder, handlers, and both Knockout and React runtime implementations.
• Heavy use of webpack configs for multiple targets (designer UI, runtime UI, publisher, static data mocks).
Insights from README
• Purpose: a managed or self-hosted portal that ships daily from master (unstable) and official releases.
• It relies on Azure APIM service REST APIs and supports customization by community widgets.
• Browser/Client UI
– Designer/Admin SPA (React/TSX + Knockout bindings for widget editors)
– Runtime SPA (widget modules for API consumers)
• CI/CD & Publishing Pipeline
– GitHub Actions / .pipeline scripts
– scripts.v2 / scripts.v3 CLI tools
• Portal Backend APIs (no custom server in repo)
– Azure API Management MAPI REST endpoints (management API)
– Azure AD / B2C OAuth2/OIDC endpoints
• Storage & Configuration
– Azure Blob Storage for media and static assets
– APIM internal storage for portal configuration
• Telemetry & Logging
– Azure Application Insights via appInsightsLogger
b. Relationships & interactions:
1. Developer/admin uses Designer SPA → communicates to Publishing pipeline (via scripts or GitHub Actions) → pushes JSON config, widgets, and static assets to APIM management API.
2. End user loads Runtime SPA (hosted in Azure blob/CDN or from APIM) → SPA calls MAPI REST to fetch API definitions, operations, products, user profiles.
3. SPA invokes Azure AD B2C for sign-in/up flows → receives OAuth tokens → passes to MAPI client for authenticated calls.
4. SPA assets are versioned/bundled by webpack and published via pipeline to blob storage or directly to APIM.
5. Telemetry events from SPA are sent to Application Insights.
c. Architectural patterns & design principles:
• Widget-based modularity: each feature is a self-contained design/publish/runtime module.
• MVVM: Knockout.js view models + model binders.
• Progressive enhancement: both Knockout and React runtimes co-exist.
• CI/CD as code: GitHub Actions and build scripts.
• Abstraction layers: clients/services, persistence providers, authentication providers allow pluggability.
d. Key technologies/frameworks:
– TypeScript + ES modules
– React + Knockout.js
– Webpack multi-target configs
– Azure API Management REST (MAPI)
– Azure AD / B2C OAuth2/OIDC
– Azure Blob Storage
– GitHub Actions / Azure Pipelines
– Application Insights SDK