MuleSoft API governance that works: from a Confluence guideline to enforced policies

Most API guidelines live in Confluence and nowhere else. How to turn a MuleSoft API governance guideline into machine-checked rules, enforced policies and a compliance score, step by step.

The short answer

API governance is the set of rules that decides how APIs are designed, secured, built, deployed and retired, plus the mechanisms that make sure those rules are followed. In MuleSoft, governance only works when every rule in the written guideline has an enforcement point: a design-time ruleset, a pipeline check, a runtime policy or a scheduled compliance check. A rule without an enforcement point is a wish.

Why the Confluence guideline is not enough

Almost every organisation we meet has an API guideline. It is usually good: naming conventions, versioning, error formats, security classes, logging rules. It is also usually unenforced. Developers read it once, new team members never, and external partners interpret it in their own way.

A real example: a German association with more than 1.8 million members had a careful API security guideline in Confluence and even its own linter in the CI pipeline, with 31 rules for Mule code and API contracts. When we compared the guideline with what was running in API Manager, none of the eight deployed APIs was compliant. JWT validation was missing on all of them. The linter checked the code in the repository; nobody checked what was really deployed.

Governance is not what you write down. It is what you check, every day, automatically.

The four enforcement points

We map every rule of a guideline to one of four enforcement points. Each one catches a different kind of mistake.

1. Design time: the specification. Rules about the API contract belong in a ruleset that runs on every specification in Exchange. Anypoint API Governance can apply rulesets to RAML and OAS assets and show conformance per asset. Typical rules: every operation declares 400, 401, 403, 429 and 500; every API has a security scheme, including health endpoints; names follow the convention; examples exist for every response.

2. Build time: the pipeline. Rules about the Mule code belong in the CI pipeline: a linter on the Mule XML, MUnit with a coverage threshold, and a check that no secrets or keystores are packaged. A failed rule fails the build. This is where most organisations already invest, and it is good, but it only sees the repository.

3. Deploy time: the link between app and API. The most underrated rule: no deployment without API autodiscovery. If the application is not linked to its API instance, API Manager cannot apply any policy. Policies themselves should be applied automatically from the API’s security class, using the API Manager APIs in the deployment pipeline, not by hand in the UI.

4. Run time: what is really live. A scheduled check compares the deployed estate with the guideline: which policies are active per API and environment, which internal APIs have public endpoints, which versions run against which published specification. This is the only enforcement point that sees drift, manual changes and forgotten deployments.

Security classes: the heart of a working guideline

Do not define policies per API. Define a small number of security classes and assign each API to one class. Each class has required and forbidden policies. A typical set:

• External, machine to machine (partners, B2B): client credentials or JWT validation, client ID enforcement, rate limiting or SLA tiers, IP allowlist where possible.
• External, end user (apps, portals): JWT validation against your identity provider, rate limiting, threat protection.
• Internal process API: JWT validation or client ID enforcement, no public endpoint.
• Internal system API: client ID enforcement, no public endpoint, callable only by process APIs.

With classes, the check becomes simple: read the class from the API’s metadata, read the active policies from API Manager, compare. The result is a compliance score per API, per class and for the whole estate.

From prose to rules: how to translate a guideline

The translation step is where governance projects fail or succeed. We turn each paragraph of the guideline into one or more checklist items with five fields:

• ID and short title, for example SEC-004 “Policies match the security class”.
• Source: a link to the guideline page and its version, so every finding can be traced back.
• Severity: critical, major or minor. Critical means it blocks production.
• Checker type: rule (fully automatic), review (needs an expert or an assisted review) or manual.
• Parameters: the concrete values, such as the required policies per class or the naming pattern.

In our experience, about 75 to 80 percent of a typical guideline can be checked fully automatically. The rest needs a reviewer, and that is fine, as long as it is visible which items were not checked.

Three traps we see again and again

Contradicting pages. Guidelines grow over time. One page says “never log in an error handler”, another says “log once where the error is mapped”. During the translation step, such conflicts surface. Collect them and let the architecture board decide once.

Rules nobody can check. “Code must be readable” is not a rule. “Inline DataWeave longer than one line is not allowed” is. Rewrite vague rules until they are checkable, or mark them as review items.

Exceptions without an expiry date. Every estate needs exceptions: a legacy API that cannot support JWT yet, a partner that needs basic authentication. Record each exception with an owner and an expiry date. An exception without expiry is a permanent hole.

Checklist: governance that is enforced

• Every rule in the guideline has an ID, a severity, a source link and an enforcement point.
• Every API has a security class in its metadata.
• Required and forbidden policies are defined per class, not per API.
• A design-time ruleset runs on every specification in Exchange.
• The pipeline fails on secrets, packaged keystores, missing tests and lint errors.
• No deployment without API autodiscovery, in every environment.
• Policies are applied by the pipeline from the class, not by hand.
• A scheduled check compares live policies, endpoints and versions with the guideline.
• The compliance score is visible to architects and to the business owner.
• Exceptions have an owner and an expiry date.
• Guideline conflicts are logged and decided by one body.

Where to start

Do not start with tooling. Start with a measurement: how compliant is the estate today, against your own guideline? That number creates the urgency and the priorities. In our MuleSoft Health Check we translate your guideline into checkable items and run them against everything deployed, using our analysis platform MuleInsights. Governance then becomes a regular task of your Center for Enablement, not a one-off project.

FAQ

What is API governance in MuleSoft?
The rules for designing, securing, building, deploying and retiring APIs on the Anypoint Platform, plus the checks that enforce them: rulesets on specifications, pipeline checks, API Manager policies and scheduled compliance checks.

Is Anypoint API Governance enough?
It covers design-time conformance of specifications well. It does not check your Mule code, your deployments or whether live policies match your security classes. You need all four enforcement points.

How much of a guideline can be checked automatically?
In our experience about 75 to 80 percent. The rest are review items, which should be visible as “not checked” rather than silently ignored.

Who owns API governance?
Usually the Center for Enablement or the integration architecture team. The business owner of each API owns its exceptions.

By Bassem Fawaz · #mulesoft #api-governance #api-security #anypoint #c4e