How awslabs/aws-api-gateway-developer-portal works
Project Type and Purpose
• This is a full-stack, serverless developer portal for AWS API Gateway.
• Purpose: Provide an interactive, self-service portal (React SPA) for API consumers to browse docs, register/login (Cognito), obtain API keys, “Try It Out,” view metrics, generate SDKs, and submit feedback.
High-Level Architecture Inferred from File Tree & README
• Frontend (“dev-portal” directory): React application built and deployed as static assets to S3, served through CloudFront (with optional custom domain).
• Backend (“lambdas” directory): Multiple Lambda functions behind an API Gateway REST API. These include:
• Authentication/identity triggers (Cognito pre-signup, post-confirmation, post-authentication)
• Core routes for catalog, accounts, subscriptions, feedback, marketplace workflows, SDK generation, asset uploads
• Auxiliary lambdas (catalog-updater, static-asset-uploader, user/group import-export, CloudFront security, common shared layer)
• Infrastructure as code (cloudformation/template.yaml): Defines API Gateway, Lambda functions, Cognito User Pool, DynamoDB tables (Customers, UsagePlans), S3 buckets (static assets, artifacts), CloudFront distribution, IAM roles, Route53 (optional).
• Deployment scripts: SAM packaging/deploy, SAR option, custom scripts under “scripts/” for development workflows.
Core Components
a. Static Website Hosting
• S3 bucket (DevPortalSiteS3Bucket) storing React build
• CloudFront distribution + optional Route53 custom domain
b. Client Application
• Browser runs React SPA, loads JS/CSS from CloudFront • Calls API endpoints
c. API Layer
• API Gateway REST API (single entry point, proxies to Lambdas)
d. Compute Layer (Lambda functions)
• User management triggers (Cognito PreSignUp, PostConfirm, PostAuth)
• Admin/Account management lambdas (approve/deny/promote/resend invite)
• Catalog management (list, import generic swagger/OpenAPI, visibility toggles, SDK generation)
• Subscription flows (subscribe/unsubscribe usage plans, marketplace confirm)
• Feedback service
• Asset uploader (push React build and custom content to S3)
• Catalog-updater (poll or trigger to refresh API specs)
• Shared utilities layer (common code)
e. Data Stores & External Services
• DynamoDB tables (Customers, API catalog, Usage plans, feedback)
• Cognito User Pool & Identity Pool (authentication/authorization)
• AWS API Gateway usage plans & API keys
• S3 (artifacts bucket for Lambda zips, static assets bucket)
• CloudWatch Logs (for Lambda tracing)
• (Optional) AWS Marketplace SNS topic and listener for subscription events
Relationships & Data Flows
• User → Browser → CloudFront → S3 static site
• SPA → API Gateway → specific Lambda (based on route)
• Lambda ↔ DynamoDB (read/write user profiles, API catalog entries, usage records)
• Lambda ↔ API Gateway service APIs (create/list API keys, usage plan associations, export SDK)
• React SPA ↔ Cognito SDK calls for sign-up, login, token refresh
• Catalog-updater Lambda triggered (e.g., event or cron) → fetch external Swagger/OpenAPI → store in DynamoDB/S3
• Asset-uploader Lambda triggered post-build → upload new SPA build to S3
Architectural Patterns & Design Principles
• Serverless microservices: each Lambda implements a focused function/route
• Single-page application (SPA) decoupled from backend API
• Infrastructure as code (CloudFormation/SAM) for reproducible deployment
• Layered security: Cognito for auth, IAM roles for Lambdas, CloudFront HTTPS
• Event-driven asset and catalog updates via Lambda triggers/SNS
Essential Elements
• Clear labels (e.g., “User,” “React SPA,” “API Gateway REST API,” “Lambda: AccountRoutes,” “DynamoDB: CustomersTable”)
• Arrowheads for data flow direction