Skip to main content

API Documentation — Process & Architecture

This page replaces the old Confluence page "API documentation" (SKM space), which describes a static single-page site published from the api2-docs GitLab repo to an api.mambu.com S3 bucket. That pipeline is retired. All current API reference content — API v2, API v1, Streaming, Audit Trail, and the legacy Mambu Payments Gateway (MPG) — is part of this Docusaurus site and repository. Do not use the old Confluence page or the api2-docs repo as a reference going forward.

Outputs​

docs.mambu.com is the single Mambu documentation site, built with Docusaurus. It hosts the support/user documentation as well as all API references, unlike the old setup where API docs lived on a separate api.mambu.com page. Visitors switch between APIs using the Mambu APIs dropdown in the top navbar (docusaurus.config.ts), not the old "More APIs" menu. Site search is Algolia, not the old lunr.js implementation.

The site currently documents:

  • API v2 and API v1 — the core banking engine APIs.
  • Streaming API — currently only the original (v1) version; this is the API this page's request is about extending.
  • Audit Trail
  • Mambu Payments Gateway (MPG) — the legacy payments product, being sunset. It is not the current Mambu Payments product.

The current Mambu Payments product (formerly Numeral) has its own separate documentation site, docs.mambupayments.com, which is not part of this repository. Links to it exist from docs/docs/mambu-payments.mdx and the navbar, but its content is owned and published elsewhere.

Changes & Contributing​

Content changes go through standard GitLab flow — there is no more manual tag-and-S3-upload step for routine changes:

  1. Clone this repo and create a branch.
  2. Make your changes.
  3. Open a merge request. GitLab CI automatically builds and deploys an isolated preview at https://docs.mambu.com/mr-{ID}/ so reviewers can see the change live before it ships — see Merge Request Preview Environments.
  4. Once approved and merged to main, CI deploys the change to production automatically.

If you don't have the access or time to make the change yourself, open a ticket in the DOC Jira project (not the old "SSKM" project referenced by the retired Confluence page) or ask in the documentation team's Slack channel.

OpenAPI specs themselves are not edited directly in this repo except for narrow, ticket-tracked exceptions (see Patching known spec defects below). Field- and endpoint-level content comes from the source spec and is refreshed automatically; if a spec is wrong or a field is missing at source, the fix belongs with the team that owns that API.

Inputs​

  • Hand-written conceptual pages — introductions, authentication, base URLs, versioning, custom fields, etc. Written by tech writers, live under docs/api/pages/<api-name>/*.mdx in this repo, and are the only part of an API's docs edited directly and by hand.
  • OpenAPI specs — retrieved automatically before every build by scripts/openapi/retrieve-oas.sh, then pre-processed (scripts/main.js) into swagger_files/v2/ and swagger_files/v1/. Sources vary by API:
    • Core API v2 — auto-discovered from the current staging tenant's /api/swagger/resources endpoint (OpenAPI v3, falling back to v2). New fields or operations on existing endpoints appear automatically on the next build.
    • Core API v1 — retrieved from the tenant/legacy sources into swagger_files/v1.
    • Streaming (v1) — its own microservice, spec fetched from a fixed /api/v1/swagger.json path on the tenant, independent of the core API's version scheme. This is exactly why a v2 Streaming spec needs new, explicit wiring rather than just "showing up" — see below.
    • Functions — pulled from a YAML file in a separate GitLab repo.
    • Legacy Mambu Payments Gateway (MPG) — retrieved from payments.dev.mambucloud.com.
    • Known upstream spec defects are patched at build time in scripts/openapi/spec-patcher.js — temporary, ticket-tracked overrides (e.g. an incorrect readOnly flag) that get removed once the owning team fixes the spec at source.

Brand-new APIs, or a new major version of an existing one (like Streaming v2), are the one case that is never picked up automatically — they need to be wired in manually, as described next.

Adding a new API, or a new version of an existing API​

This is the actual answer to "how do I add v2 articles for Streaming": there's no separate v1/v2 toggle to flip. The established pattern (used for core API v1 vs v2 today) is to treat the new version as its own top-level API, sitting alongside the old one rather than nested inside it, so old links and content never conflict with the new version. Concretely:

  1. Get the OpenAPI spec. A file, a URL, or a tenant endpoint. For a new microservice/major-version spec like Streaming v2, this is usually a new fetch in scripts/openapi/retrieve-oas.sh (mirroring the existing static Streaming v1 fetch), so it refreshes automatically on every build instead of being manually maintained.
  2. Register it for doc generation in docusaurus.config.ts, as a new docusaurus-plugin-openapi-docs entry (specPath, outputDir, sidebarOptions) — this is what turns the spec into the request/response reference pages.
  3. Write the conceptual pages under a new docs/api/pages/<api-name>-v2/ (or similar) directory: an index/welcome page, "About" page, base URLs, authentication, and anything else that differs from v1. Use the existing docs/api/pages/api-v2/ or docs/api/pages/streaming/ pages as a structural template — copy, don't invent, the sections that still apply.
  4. Wire the sidebar in sidebars/api-sidebars.js: import the plugin-generated sidebar file (docs/api/<api-name>/sidebar.ts) and add a new top-level category for the new version, following the pattern already used for API V2 / API V1 (sidebars/api-sidebars.js:19 and :80) rather than nesting it inside the existing "Streaming" category.
  5. Add a navbar entry if it should be directly discoverable from the Mambu APIs dropdown in docusaurus.config.ts.
  6. Open an MR, review it via the MR preview URL, then merge — no manual S3 upload or GitLab tag is needed.

Patching known spec defects​

Occasionally a source OpenAPI spec is simply wrong (a field marked readOnly when the API actually accepts it, a missing required array, etc.). These are fixed temporarily in scripts/openapi/spec-patcher.js, each patch commented with the reason and a DOC ticket reference, and removed once the owning team corrects the spec at its source. This is the preferred short-term fix — it keeps the public docs accurate without waiting on an upstream release, but it is explicitly temporary and tracked, not a substitute for fixing the real spec.

Last updated on