2.3 API Mocking Service, Documentation & Anypoint Exchange Publishing
Key Takeaways
- The Anypoint API Mocking Service generates an active, zero-code HTTP endpoint from a RAML specification, enabling client applications to simulate API interactions before backend flows are developed.
- Mocking endpoints can be accessed via Public URLs (for open testing) or Private URLs (which require Anypoint Platform authentication headers), and behavior can be controlled using mocking headers.
- The interactive API Console auto-generates live, human-readable documentation directly from RAML markdown comments, schemas, and example payloads.
- Publishing an API specification to Anypoint Exchange requires distinguishing between the RAML 'API Version' (interface contract, e.g., 'v1') and the Exchange 'Asset Version' (immutable SemVer package coordinate, e.g., '1.0.0').
- Anypoint API Governance automatically evaluates published specifications against organizational rulesets (such as OWASP API Security and naming conventions) to enforce compliance.
API Mocking Service, Documentation & Anypoint Exchange Publishing
Designing a comprehensive RAML specification is only the first step in the API-led development lifecycle. To realize the full benefits of contract-first development, organizations must simulate endpoints for consumer validation, generate interactive documentation, and publish discovery assets to Anypoint Exchange. This collaborative loop ensures that APIs are validated, discoverable, and governed across the enterprise.
1. API Designer Capabilities & Interactive Authoring
Anypoint Design Center - API Designer is a cloud-based web IDE (also available in desktop form) for designing, documenting, and testing RAML 1.0 and OAS specifications.
+---------------------------------------------------------------------------------------------------+
| ANYPOINT API DESIGNER INTERFACE |
| |
| +-------------------+-----------------------------------------+-----------------------------+ |
| | FILE BROWSER | RAML CODE EDITOR (Context-Aware) | API CONSOLE & MOCKING |
| | - api.raml | #%RAML 1.0 | /customers |
| | - types/ | title: Customer API | [GET] Retrieve all |
| | - Customer.raml | /customers: | [POST] Create customer |
| | - traits/ | get: | |
| | - pageable.raml | responses: | [Try It Button] |
| | - exchange_mods/ | 200: | Live Mock Response (200 OK) |
| +-------------------+-----------------------------------------+-----------------------------+ |
+---------------------------------------------------------------------------------------------------+
Key Features of API Designer:
- Context-Aware Shelf: Displays contextual code completion suggestions for valid RAML nodes, facets, and data types based on the current cursor indentation.
- Real-Time Parser & Linter: Detects YAML syntax errors, missing mandatory properties, indentation mistakes, and invalid regex patterns in real time.
- Integrated Git Repository: Every Design Center project is backed by an internal Git repository that tracks commits, branches, and revision history.
- Visual Editor Mode: Allows non-technical stakeholders to inspect and modify resources, query parameters, and documentation without editing raw YAML.
2. The API Mocking Service: Simulating Endpoints
The API Mocking Service provides simulated HTTP endpoints based directly on the RAML definition and its example payloads. No Mule application, runtime engine, or backend database is required to test the API.
+---------------------------------------------------------------------------------------------------+
| API MOCKING SERVICE WORKFLOW |
| |
| [API Designer / Exchange] |
| | |
| v (Enables Mocking Service) |
| https://mocksvc.qax.anypoint.mulesoft.com/mocks/orgId/assetId/v1/customers |
| ^ |
| | 1. HTTP GET /customers (with optional MS-Resource-Identifier) |
| | 2. Returns 200 OK + Example JSON Payload |
| | |
| [Consumer App / Mobile Developer / Postman] |
+---------------------------------------------------------------------------------------------------+
Public vs. Private Mocking URLs:
- Private Mocking URL: Used inside Design Center or when testing via the interactive API Console. Requires Anypoint Platform authentication (Bearer token or session cookie).
- Public Mocking URL: A shareable URL that can be accessed by external consumers or automated test scripts outside Anypoint Platform without requiring platform login credentials.
How Mock Data is Generated:
- Explicit Examples: If the RAML defines
example:orexamples:blocks, the Mocking Service returns the exact example data defined in the specification. - Synthesized Data: If no example is declared, the Mocking Service inspects the
type:and facets (e.g.,type: string,minimum: 10) to generate synthetic placeholder data.
Controlling Mock Responses with Headers:
Consumers can control the Mocking Service behavior by passing specific HTTP headers:
MS-Resource-Identifier: When multiple examples are defined underexamples:, this header specifies which named example to return.X-Mock-Response-Code: Forces the mocking service to return a specific HTTP status code (e.g.,X-Mock-Response-Code: 400to test how the client handles validation failures).
3. Interactive API Console & Documentation Generation
The API Console is an interactive documentation viewer rendered automatically in API Designer, Anypoint Exchange, and standalone API portals.
+---------------------------------------------------------------------------------------------------+
| INTERACTIVE API CONSOLE |
| |
| [Documentation View] [Try It Sandbox] |
| - Markdown Descriptions - Base URI Selector (Mocking Service vs Live Endpoint) |
| - URI / Query Parameters - Parameter Input Fields (e.g., customerId = CUST-101) |
| - Request / Response Headers - Headers (client_id, Authorization) |
| - JSON Schema & Payload Types - [Send Request Button] -> Returns Live HTTP Status & Body |
+---------------------------------------------------------------------------------------------------+
Best Practices for Rich Documentation:
- Use the root
documentation:facet with Markdown headers, bullet points, and code snippets to explain API authentication workflows and rate limits. - Provide detailed
description:annotations on every resource, method, query parameter, and JSON property. - Provide comprehensive
examples:representing both success payloads and standard error responses.
4. Publishing to Anypoint Exchange
Anypoint Exchange is the enterprise catalog and discovery hub for all reusable IT assets—including RAML/OAS API specifications, API fragments, Mule connectors, integration templates, and custom policies.
+---------------------------------------------------------------------------------------------------+
| PUBLISHING TO ANYPOINT EXCHANGE |
| |
| [API Designer Project] |
| | |
| v (Click 'Publish to Exchange') |
| +-------------------------------------------------------------------------------------------+ |
| | ASSET PUBLICATION COORDINATES: | |
| | - Asset Name: Customer Accounts Experience API | |
| | - Asset ID: customer-accounts-exp-api | |
| | - Organization ID: 7f8a9b1c-3e2d-4f5a-8b9c-0d1e2f3a4b5c (Enterprise Org) | |
| | - API Version: v1 (Semantic Interface Contract) | |
| | - Asset Version: 1.0.0 (Immutable Package SemVer) | |
| +-------------------------------------------------------------------------------------------+ |
+---------------------------------------------------------------------------------------------------+
Crucial Exam Concept: API Version vs. Asset Version
Understanding the distinct roles of API Version and Asset Version is a major exam topic:
| Attribute | API Version | Asset Version |
|---|---|---|
| Definition | Semantic version of the API interface contract | Package release version of the Exchange catalog asset |
| RAML Location | Defined in RAML root: version: v1 | Set during publishing dialog in Exchange |
| Format | Arbitrary string (e.g., v1, v1.0, v2) | Strict SemVer: Major.Minor.Patch (e.g., 1.0.0) |
| When to Increment | Only when interface contracts change (e.g., breaking endpoint changes) | With every publish action to Exchange |
| Immutability | Can span multiple asset versions (e.g., v1 on asset 1.0.0, 1.0.1, 1.1.0) | Strictly Immutable. You cannot re-publish asset version 1.0.0 |
+---------------------------------------------------------------------------------------------------+
| API VERSION VS. ASSET VERSION LIFECYCLE |
| |
| Publish #1: Fix typo in description --> API Version: v1 | Asset Version: 1.0.1 (Patch) |
| Publish #2: Add optional query parameter --> API Version: v1 | Asset Version: 1.1.0 (Minor) |
| Publish #3: Breaking change (rename field) --> API Version: v2 | Asset Version: 2.0.0 (Major) |
+---------------------------------------------------------------------------------------------------+
5. Asset Lifecycle States & Anypoint API Governance
Once an API specification is published to Exchange, it enters a managed lifecycle that communicates its stability to enterprise consumers:
+---------------------------------------------------------------------------------------------------+
| ASSET LIFECYCLE STATES |
| |
| [DEVELOPMENT] [PUBLISHED] [DEPRECATED] [DELETED] |
| Work in progress --> Stable & Active --> Retiring Soon --> Removed from Catalog |
| (Subject to change) (Approved for Use) (Existing apps work; (No longer usable) |
| no new consumers) |
+---------------------------------------------------------------------------------------------------+
Anypoint API Governance:
API Governance enables organizations to apply automated quality, consistency, and security rulesets to API specifications published in Exchange:
- Standard Rulesets: OWASP API Security Top 10, OpenAPI/RAML Best Practices, Semantic Versioning Rules, Brand/Naming Standards.
- Conformance Status:
Conformant: Specification passes all mandatory governance rulesets.Non-Conformant: Specification violates one or more rules (e.g., missing HTTPS protocol, unstandardized error structures).Not Evaluated: No governance ruleset applied to this asset type.
6. Consumer Collaboration & Asset Promotion
Anypoint Exchange functions as a self-service developer portal:
- Requesting API Access: Consumer developers discover an API in Exchange, select an SLA Tier (e.g., Bronze, Silver, Gold), and register a client application to obtain
client_idandclient_secretcredentials. - Ratings & Feedback: Consumers leave 1-to-5 star ratings, submit reviews, and report issues directly to the API publisher.
- Public API Portals: Organizations can expose selected Exchange assets publicly to external third-party developers, complete with customized branding, terms of service, and interactive API consoles.
7. Consuming a RAML-Based API: REST Connect Generated Connectors
Publishing to Exchange does more than catalogue a specification. Exchange runs REST Connect, which transparently converts a published REST API specification — RAML or OAS — into a Mule 4 connector, without the API owner writing any connector code.
+---------------------------------------------------------------------------------------------------+
| TWO WAYS TO CONSUME A RAML-DEFINED REST SERVICE |
| |
| A. GENERIC HTTP REQUEST B. REST CONNECT GENERATED CONNECTOR |
| +-------------------------------+ +-------------------------------------------+ |
| | <http:request | | Publish RAML to Exchange | |
| | method=GET | | | | |
| | path=/customers/{id}/> | | v (REST Connect converts) | |
| | | | Connector asset appears in Exchange | |
| | - You hand-build path, | | | | |
| | query params, headers | | v (add from Exchange in Studio) | |
| | - No compile-time metadata | | Typed operation per RAML method/resource | |
| +-------------------------------+ +-------------------------------------------+ |
+---------------------------------------------------------------------------------------------------+
How the Generated Connector Is Used
- The API owner publishes the RAML (or OAS) specification to Anypoint Exchange.
- Exchange generates the connector automatically; it is downloadable from the asset's Download menu, and Mule 4 connectors download as JAR files.
- In Anypoint Studio, the consuming developer adds the connector from Exchange through the Add Modules panel, exactly as they would add the Database or Salesforce connector.
- The palette then exposes one typed operation per RAML method and resource —
getCustomersCustomerId,postOrders— with DataWeave metadata for request and response bodies already in place.
| Consumption approach | When it is the right answer |
|---|---|
<http:request> | Consuming any REST endpoint, especially one with no published specification |
| REST Connect connector | Consuming a RAML/OAS-defined API already published to Exchange, where typed operations and design-time metadata reduce hand-written paths and mapping errors |
[!TIP] Two Different Things Get Generated From One RAML APIkit scaffolding generates the provider side — interface flows that implement the specification inside your own application. REST Connect generates the consumer side — a connector that calls someone else's implementation of that specification. Questions describing a team that must call a partner API defined by a published RAML are pointing at REST Connect, not APIkit.
8. Exam Watch: Core Developer Scenarios & Traps
[!IMPORTANT] Exam Rule 1: Immutability of Exchange Asset Versions Asset versions in Anypoint Exchange are immutable. If you publish an API specification as Asset Version
1.0.0, make a change in API Designer, and attempt to re-publish as1.0.0, Exchange will reject the operation. You must increment the Asset Version to1.0.1(or higher).
[!WARNING] Exam Rule 2: Simulating Unimplemented APIs When an exam question describes a scenario where client application developers need to build and test frontend screens before the backend MuleSoft integration is built, the recommended MuleSoft solution is to publish the RAML specification to Exchange and enable the API Mocking Service.
[!TIP] Exam Rule 3: Deprecation vs Deletion When an API version is being phased out in favor of a newer version, the asset state should be set to Deprecated. Deprecated APIs remain fully operational for existing registered consumer applications but warn new developers against building integrations on that version.
A mobile application team needs to start developing and testing screen flows against a new Customer Experience API. However, the backend integration team has only finished writing the RAML 1.0 specification in API Designer and has not implemented any Mule flows in Anypoint Studio. How can the integration team enable the mobile developers to immediately test against realistic endpoints?
A developer designs a RAML specification with 'version: v1' in API Designer and publishes it to Anypoint Exchange as Asset Version '1.0.0'. The developer later fixes a spelling mistake in a resource description and adds an optional query parameter. How should the developer version and publish these updates to Exchange?
What is the primary operational consequence when an API asset's lifecycle state in Anypoint Exchange is changed from 'Published' to 'Deprecated'?
An enterprise requires all RAML API specifications to enforce HTTPS protocols, include standard 500 error response structures, and adhere to camelCase naming conventions for URI parameters. How can an organization automatically validate and track adherence to these standards across all published Exchange assets?