Skip to content

Commit 586a51a

Browse files
alexpmulealexpmule
committed
docs: add onboarding, architecture patterns, and release runbook for API Console v6
- Introduced comprehensive onboarding documentation for API Console v6, detailing its purpose, architecture, and usage modes. - Added architectural decision records (ADRs) to document key design choices and component patterns. - Included a release runbook outlining the step-by-step process for versioning and publishing updates. - Created a troubleshooting guide to assist developers with common issues encountered during development and release. This documentation enhances the knowledge base for the team, streamlines the onboarding process for new contributors, and ensures consistent practices across the project.
1 parent 1b958e0 commit 586a51a

4 files changed

Lines changed: 1995 additions & 0 deletions

File tree

‎docs/team/onboarding/api-console-v6.md‎

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,334 @@
1+
# API Console v6 - Onboarding
2+
3+
> **Last Updated**: 2026-03-02
4+
> **Maintainer**: ACM Team (API Community Manager)
5+
> **Version**: 6.6.x
6+
7+
---
8+
9+
## What is API Console?
10+
11+
API Console is an interactive documentation tool that automatically generates API documentation from RAML, OAS (OpenAPI), AsyncAPI, and gRPC specifications. It's similar to Postman but embedded directly in web applications.
12+
13+
**Key Features**:
14+
- **API Navigation**: Tree view of endpoints, methods, types
15+
- **API Documentation**: Detailed docs for each endpoint/method
16+
- **API Request Panel**: "Try it" functionality to test endpoints
17+
- **Multi-spec support**: RAML, OAS 2/3, AsyncAPI, gRPC (read-only)
18+
19+
**Used by**:
20+
- Anypoint Platform (Exchange, API Designer)
21+
- API Community Manager (ACM)
22+
- APIKit
23+
- Multiple MuleSoft + Salesforce products
24+
25+
---
26+
27+
## Architecture Overview
28+
29+
### Two Versions
30+
31+
| Version | Tech Stack | Purpose | Repo |
32+
|---------|-----------|---------|------|
33+
| **v6** | LitElement, Web Components | Open source, used in most products | `mulesoft/api-console` |
34+
| **v7** | Lightning Web Components (LWC) | Salesforce Experience Cloud only | `mulesoft/api-console-lwc` |
35+
36+
This document focuses on **v6**.
37+
38+
### Two Usage Modes
39+
40+
**1. Standalone Application** (`ApiConsoleApp`)
41+
- Full app with routing, layout, navigation drawer
42+
- Entry point: `src/ApiConsoleApp.js`
43+
- Demo: `demo/standalone/index.html`
44+
45+
**2. Web Component** (`ApiConsole`)
46+
- Embeddable component (no routing/layout)
47+
- Entry point: `src/ApiConsole.js`
48+
- Host app provides layout and navigation
49+
- Demo: `demo/element/index.html`
50+
51+
### Component Hierarchy
52+
53+
```
54+
ApiConsoleApp (extends ApiConsole)
55+
└── ApiConsole (extends AmfHelperMixin(LitElement))
56+
├── api-navigation (left drawer)
57+
├── api-documentation (main content)
58+
├── api-request-panel (try it panel)
59+
└── Helper components:
60+
├── xhr-simple-request
61+
├── oauth1-authorization
62+
└── oauth2-authorization
63+
```
64+
65+
---
66+
67+
## AMF Model Architecture
68+
69+
**CRITICAL**: API Console does NOT parse API specs directly. It requires a pre-generated **AMF model**.
70+
71+
### What is AMF?
72+
73+
**AMF (AML Modeling Framework)**: MuleSoft's unified model for RAML, OAS, AsyncAPI, and gRPC.
74+
- **Format**: JSON-LD
75+
- **Version**: v6.0.0+ requires AMF v4.0.0+ (AMF model v2)
76+
- **Generator**: `@api-components/api-model-generator`
77+
78+
### AMF Concepts
79+
80+
**Declares**: Types, components, schemas
81+
**Endpoints**: API paths
82+
**Operations**: HTTP methods (GET, POST, PUT, DELETE, etc.)
83+
84+
### Model Flow
85+
86+
```
87+
API Spec (RAML/OAS/AsyncAPI/gRPC)
88+
→ AMF Parser (amf-client-js)
89+
→ AMF Model (JSON-LD)
90+
→ api-console `amf` property
91+
→ AmfHelperMixin provides querying utilities
92+
→ Renders documentation/navigation/request panel
93+
```
94+
95+
**More info**: https://a.ml/docs/
96+
97+
---
98+
99+
## Repository Structure
100+
101+
### Main Repos
102+
103+
**1. `mulesoft/api-console`** (this repo)
104+
- Main integrator component
105+
- Version: 6.6.x
106+
- Depends on: Individual components from `advanced-rest-client` org
107+
- Release cycle: Every 3 weeks on Fridays
108+
109+
**2. `mulesoft/anypoint-api-console`**
110+
- Builder for Anypoint Platform-specific bundle
111+
- Wraps `api-console` with custom configurations
112+
- Location: `builder/package.json` references `api-console` version
113+
114+
**3. `advanced-rest-client/*` (GitHub org)**
115+
- Individual Web Components used by api-console
116+
- Examples:
117+
- `api-navigation`
118+
- `api-summary`
119+
- `api-type-document`
120+
- `api-documentation`
121+
- `api-request`
122+
- Each is a separate npm package (`@api-components/<name>`)
123+
124+
### Monorepo Structure (api-console)
125+
126+
```
127+
api-console/
128+
├── src/
129+
│ ├── ApiConsole.js # Base web component
130+
│ ├── ApiConsoleApp.js # Standalone app
131+
│ └── styles/ # Component styles
132+
├── demo/
133+
│ ├── apis.json # API definitions for demos
134+
│ ├── models/ # Generated AMF models (gitignored)
135+
│ ├── vendor.js # Non-ES6 dependencies (generated)
136+
│ └── model.js # Script to generate AMF models
137+
├── test/
138+
│ ├── *.test.js # Unit tests
139+
│ └── visual/ # Visual regression tests
140+
├── docs/team/ # Team documentation
141+
│ ├── onboarding/ # Onboarding docs (this file)
142+
│ ├── runbooks/ # Operational procedures
143+
│ └── patterns/ # Architectural decisions
144+
└── .claude/ # Claude Code working files (gitignored)
145+
├── skills/ # Automation skills
146+
└── investigations/ # Bug analysis files
147+
```
148+
149+
---
150+
151+
## Tech Stack
152+
153+
### Core Technologies
154+
155+
- **LitElement 2.x**: Base class for Web Components
156+
- **Web Components**: Custom elements with Shadow DOM
157+
- **AMF**: API modeling framework
158+
- **Polymer**: Legacy components (being phased out)
159+
- **CodeMirror**: Code editor (bundled in vendor.js)
160+
161+
### Testing
162+
163+
- **@web/test-runner**: Test framework (NOT Jest - Jest has poor Shadow DOM support)
164+
- **Playwright**: Browser automation (chromium + firefox)
165+
- **Visual regression**: `@web/test-runner-visual-regression`
166+
167+
### Build & Dev
168+
169+
- **Rollup**: Production bundler
170+
- **web-dev-server**: Development server
171+
- **npm workspaces**: Monorepo (v6 only, not for individual components)
172+
173+
---
174+
175+
## API Specification Support
176+
177+
| Spec | Version | Support Level | Try It Panel |
178+
|------|---------|---------------|--------------|
179+
| **RAML** | 0.8, 1.0 | ✅ Full | ✅ Yes |
180+
| **OAS** | 2.0, 3.0 | ✅ Full | ✅ Yes |
181+
| **AsyncAPI** | 2.x | ✅ Read-only | ❌ No (not REST) |
182+
| **gRPC** | Proto3 | ✅ Read-only | ❌ No (RPC protocol) |
183+
184+
**Note**: gRPC and AsyncAPI are auto-detected and hide the "Try it" panel.
185+
186+
---
187+
188+
## Related Teams & Contacts
189+
190+
| Team | Point of Contact | Responsibility |
191+
|------|------------------|----------------|
192+
| **API Designer** | Leandro Bauret (Dev)<br>Eduardo Cominguez (Manager) | Consumes api-console in Designer |
193+
| **Exchange** | Nicolas Escalante (Dev)<br>Mariano Campo (Manager) | API documentation display |
194+
| **AMF** | Nicolas Schejtman (Dev)<br>Martin Gutierrez (Manager) | AMF parser and model |
195+
| **APIkit** | Chakravarthy Parankusam (Manager) | Runtime API implementation |
196+
| **Mocking Service** | Roberto Ciccone (Dev)<br>Diego Macias (Manager) | API mocking |
197+
| **ACM Team** | #acm-team (Slack) | Maintains v6 and v7 |
198+
199+
---
200+
201+
## Essential Commands
202+
203+
### First-time Setup
204+
205+
```bash
206+
git clone git@github.com:mulesoft/api-console.git
207+
cd api-console
208+
npm install
209+
npm run prepare # Build vendor.js + generate AMF models
210+
```
211+
212+
**⚠️ Important**: Always run `npm run prepare` after cloning. It builds non-ES6 dependencies (vendor.js) and generates demo models.
213+
214+
### Development
215+
216+
```bash
217+
npm start # Dev server at demo/index.html
218+
npm run start:server # Parsing server with debug
219+
npm run build:models # Generate AMF models from demo/apis.json
220+
```
221+
222+
### Testing
223+
224+
```bash
225+
npm test # All tests (unit + visual regression)
226+
npm run test:watch # Watch mode (chromium only)
227+
npm run test:visual # Visual regression only
228+
npm run test:visual:update # Update visual baselines
229+
```
230+
231+
### Building
232+
233+
```bash
234+
npm run build # Production build to dist/
235+
npm run build:vendor # Build vendor.js (CodeMirror + crypto)
236+
```
237+
238+
---
239+
240+
## Learning Resources
241+
242+
### Documentation
243+
244+
- **Full docs**: https://docs.api-console.io
245+
- **AMF**: https://a.ml/docs/
246+
- **AMF GitHub**: https://github.com/aml-org/amf
247+
- **API Components**: https://github.com/advanced-rest-client
248+
- **LitElement**: https://lit.dev/docs/v1/
249+
250+
### Specifications
251+
252+
- **RAML**: https://raml.org/
253+
- **OAS**: https://swagger.io/specification/
254+
- **AsyncAPI**: https://www.asyncapi.com/docs/reference/specification
255+
256+
### Internal Resources
257+
258+
- **Onboarding meetings**:
259+
- Part 1: APIC basics
260+
- Part 2: Troubleshooting example
261+
- **Figma designs**: Authorization migration
262+
- **Slack**: #api-console-cloud-sync (releases), #api-line (general)
263+
264+
---
265+
266+
## Development Workflow
267+
268+
### Typical Development Flow
269+
270+
1. **Clone repo** + run `npm run prepare`
271+
2. **Create feature branch** (NEVER commit to master directly)
272+
3. **Make changes** to components
273+
4. **Test locally**: `npm start` + manual testing
274+
5. **Run tests**: `npm test` (must pass)
275+
6. **Create PR** via GitHub web UI (gh CLI doesn't work with EMU)
276+
7. **Wait for review** + CI checks (Linux + Windows)
277+
8. **Merge** → Auto-publishes to npm (if version bumped)
278+
279+
### Git & GPG Requirements
280+
281+
**⚠️ CRITICAL**: This is a `mulesoft/*` repository. Before committing:
282+
283+
```bash
284+
mulesoft-git # Configure GPG signing with alexperez@mulesoft.com
285+
```
286+
287+
**Verify signature**:
288+
```bash
289+
git log --show-signature -1
290+
```
291+
292+
**Must show**: `Good signature from "alexp mule <alexperez@mulesoft.com>"`
293+
294+
---
295+
296+
## Common Pitfalls
297+
298+
### DON'T:
299+
- ❌ Commit directly to master/main (always create branch)
300+
- ❌ Forget to run `mulesoft-git` before committing
301+
- ❌ Use Jest for testing (use @web/test-runner)
302+
- ❌ Parse API files directly (use AMF model)
303+
- ❌ Modify AMF model structure (it's an external standard)
304+
- ❌ Import CodeMirror/crypto as ES modules (use vendor.js)
305+
- ❌ Use `gh pr create` (EMU account doesn't work with mulesoft/* repos)
306+
307+
### DO:
308+
- ✅ Run `npm run prepare` after cloning
309+
- ✅ Run `mulesoft-git` before committing
310+
- ✅ Test in both chromium and firefox (visual differences exist)
311+
- ✅ Use `AmfHelperMixin` utilities for AMF querying
312+
- ✅ Create PR via GitHub web UI
313+
- ✅ Update visual regression baselines when UI changes intentionally
314+
315+
---
316+
317+
## Next Steps
318+
319+
After reading this onboarding:
320+
321+
1. **Read**: `docs/team/runbooks/api-console-v6-release.md` - Learn release process
322+
2. **Read**: `docs/team/runbooks/api-console-v6-troubleshooting.md` - Common issues
323+
3. **Read**: `docs/team/patterns/api-console-architecture.md` - Technical decisions
324+
4. **Clone repo** + run through essential commands
325+
5. **Join Slack**: #api-console-cloud-sync, #api-line
326+
6. **Ask questions**: Tag @alexperez or team in Slack
327+
328+
---
329+
330+
## Questions?
331+
332+
- **Slack**: #api-line (general), #acm-team (internal)
333+
- **GitHub Issues**: https://github.com/mulesoft/api-console/issues
334+
- **Email**: arc@mulesoft.com

0 commit comments

Comments
 (0)