---
schema_version: "1"
id: 3b5e32084da3f5c9f26d499dfb6a6467ef2b1523802770620f2e01b97c4b0f4d
title: APIkit for REST Module Reference
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/apikit/latest/apikit-4-xml-reference.md
canonical_url: https://docs.mulesoft.com/apikit/latest/apikit-4-xml-reference
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 59de404cf93d4da47cce4515617b15d07b293ee51a987ba1f96b981732bc0ada
description: MuleSoft Documentation Site
release: 4.x
latest: true
---
---
product: APIkit
version: 4.x
is-latest-version: true
---

# APIkit for REST Module Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Configure the APIkit for REST module in Mule: declare the Maven dependency, add `apikit:config`, and
place the `apikit:router` and optional console and flow mappings in your XML. This reference lists
dependency coordinates, namespaces, schema locations, and element attributes you use when you
implement or troubleshoot REST APIs.

## APIkit for REST Dependency Information

<dependency>
  <groupId>org.mule.modules</groupId>
  <artifactId>mule-apikit-module</artifactId>
  <version>LATEST\_VERSION</version> **(1)**
  <classifier>mule-plugin</classifier>
</dependency>

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>Check <a href="https://docs.mulesoft.com/release-notes/apikit/apikit-release-notes">APIkit release notes</a> to get the <strong>LATEST_VERSION</strong>.</td></tr></tbody></table>

## APIkit for REST Configuration and Operations

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element Name</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p><code>apikit:config</code></p></div></div></td><td><div><div><p>APIkit configuration</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p><code>apikit:console</code></p></div></div></td><td><div><div><p>Property of <code>config-ref</code> in the <code>http:listener</code> element in the api-console flow that defines the API console URL</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p><code>apikit:flow-mappings</code></p></div></div></td><td><div><div><p>Container for one or more <code>apikit:flow-mapping</code> elements that map API resources and actions to flows</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p><code>apikit:flow-mapping</code></p></div></div></td><td><div><div><p>Maps a resource and action from the API specification to a specific Mule flow</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p><code>apikit:router</code></p></div></div></td><td><div><div><p>REST routing message processor nested in the flow element</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

### apikit:config Attributes

The `apikit:config` attributes are of type `NonBlankString`.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Attribute Name</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>outboundHeadersMapName</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Name of the map that contains response headers.</p></div></div></td></tr><tr><td><div><div><p><code>httpStatusVarName</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Name of the variable that stores the HTTP status code in the response.</p></div></div></td></tr><tr><td><div><div><p><code>keepRamlBaseUri</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Alias for the equivalent <code>keepApiBaseUri</code> attribute.</p></div><div><p>This attribute is deprecated as of version APIkit 1.2.0. Included to provide compatibility with APIkit 1.1.x.<br>Use <code>keepApiBaseUri</code> instead of <code>keepRamlBaseUri</code> in your API implementations.</p></div></div></td></tr><tr><td><div><div><p><code>name</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Configuration name that other elements, such as <code>apikit:router</code>, reference.</p></div></div></td></tr><tr><td><div><div><p><code>raml</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Alias for the equivalent <code>api</code> attribute.</p></div><div><p>This attribute is deprecated as of version APIkit 1.2.0. Included to provide compatibility with APIkit 1.1.x.<br>Use <code>api</code> instead of <code>raml</code> in your API implementations.</p></div></div></td></tr><tr><td><div><div><p><code>parser</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Parser used to validate requests.</p></div><div><p>Attribute valid for APIkit 1.2.0 and later.</p></div><div><p>Possible values are:</p></div><div><ul><li><p>AUTO</p><div><p><strong>APIkit Router</strong> starts by using AMF. If it has errors, it starts by using the RAML parser.</p></div></li><li><p>AMF</p><div><p><strong>APIkit Router</strong> uses AMF to read the API and validate incoming requests.</p></div></li><li><p>RAML</p><div><p><strong>APIkit Router</strong> starts by using AMF, and if it has errors, it starts by using the RAML parser.</p></div></li></ul></div><div><p>Default Value: AUTO.</p></div></div></td></tr><tr><td><div><div><p><code>api</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Root API file location.</p></div><div><p>This attribute is valid for APIkit 1.2.0 and later.</p></div><div><p>The <code>api</code> attribute can be any URL, the relative path to a file located under <code>src/main/resources/api</code>, or the <code>API Sync</code> resource path.</p></div></div></td></tr><tr><td><div><div><p><code>keepApiBaseUri</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Attribute valid for APIkit 1.2.0 and later.</p></div><div><p>When set to <code>false</code>, APIkit rewrites the <code>baseUri</code> in the RAML definition of the API.<br>If set to <code>true</code>, APIkit does not rewrite the <code>baseUri</code> field.</p></div></div></td></tr></tbody></table>

If you use APIkit behind a reverse proxy and set `keepRamlBaseUri` to `true`, use **API Console** to
put the URL of a proxy in the `baseUri` property.

### apikit:router Attributes

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Attribute Name</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>disableValidations</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Disables validations of requests.</p></div></div></td></tr><tr><td><div><div><p><code>headerStrictValidation</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Validates that request headers are defined in the RAML file or belong to a well-known set of headers.</p></div></div></td></tr><tr><td><div><div><p><code>queryParamsStrictValidation</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Validates that request query parameters are defined in the RAML file.</p></div></div></td></tr></tbody></table>

### OpenTelemetry Route on the HTTP Span

When `apikit:router` matches a request, APIkit records the matched route on the root HTTP span in
OpenTelemetry traces. On Mule runtime 4.13 and later, the `http.route` attribute contains the route
template, and the span name combines the HTTP method and that route, for example
`GET /orders/{orderId}`. You can identify the specific API operation in each trace. On earlier Mule
runtimes, the root HTTP span keeps the HTTP listener path.

### apikit:flow-mapping Attributes

Use the `apikit:flow-mapping` element to route a resource and action defined in the API
specification (RAML or OpenAPI specification) to an existing Mule flow.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Attribute Name</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>resource</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Resource path from the API specification to map, for example <code>/users</code>.</p></div></div></td></tr><tr><td><div><div><p><code>action</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>HTTP method to map for the resource, for example <code>get</code> or <code>post</code>.</p></div></div></td></tr><tr><td><div><div><p><code>flow-ref</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Name of the Mule flow that handles the mapped resource and action.</p></div></div></td></tr><tr><td><div><div><p><code>content-type</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Request media type to match, for example <code>application/json</code>. When omitted, the mapping applies to any <code>Content-Type</code> for that resource and action. When set, you can route the same resource and action to different flows depending on the request media type.</p></div></div></td></tr></tbody></table>

In APIkit configuration, nest `apikit:flow-mapping` in `apikit:flow-mappings`, and nest
`apikit:flow-mappings` in `apikit:config`.

```xml
<apikit:config name="api-config" api="api/api.raml">
  <apikit:flow-mappings>
    <apikit:flow-mapping resource="/orders" action="post"
        content-type="application/json"
        flow-ref="process-json-order"/>
    <apikit:flow-mapping resource="/orders" action="post"
        content-type="application/xml"
        flow-ref="process-xml-order"/>
  </apikit:flow-mappings>
</apikit:config>
```

## APIkit for REST Namespace and Schema

xmlns:apikit="http://www.mulesoft.org/schema/mule/mule-apikit"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/mule-apikit
http://www.mulesoft.org/schema/mule/mule-apikit/current/mule-apikit.xsd"

## APIkit for REST System Properties

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>System Property</th><th>Default</th><th>Description</th><th>Since</th></tr></thead><tbody><tr><td><div><div><p><code>mule.xml.expandExternalEntities</code></p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Allows parser to expand XML external entities. The default value is <code>false</code> to prevent attacks.</p></div></div></td><td><div><div><p>1.3.7</p></div></div></td></tr><tr><td><div><div><p><code>mule.xml.expandInternalEntities</code></p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Allows parser to expand XML internal entities. The default value is <code>false</code> to prevent attacks.</p></div></div></td><td><div><div><p>1.3.7</p></div></div></td></tr><tr><td><div><div><p><code>apikit.console.disabled</code></p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Disables console.</p></div></div></td><td><div><div><p>1.3.7</p></div></div></td></tr><tr><td><div><div><p><code>apikit.console.stream.amf.model</code></p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>Streams AMF parser model to the console.</p></div></div></td><td><div><div><p>1.5.0</p></div></div></td></tr><tr><td><div><div><p><code>raml.json_schema.fail_on_warning</code></p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Fails when there is a <code>warning</code> while validating a payload when the RAML parser is configured.</p></div></div></td><td><div><div><p>1.1.15</p></div></div></td></tr><tr><td><div><div><p><code>yagi.json_duplicate_keys_detection</code></p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>Checks no duplicate JSON object field names are encountered when the RAML parser is configured.</p></div></div></td><td><div><div><p>1.1.15</p></div></div></td></tr><tr><td><div><div><p><code>yagi.json_block_unsafe_polymorphic_base_types</code></p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>Blocks the use of unsafe base types when the RAML parser is configured.</p></div></div></td><td><div><div><p>1.5.0</p></div></div></td></tr><tr><td><div><div><p><code>mule.apikit.parser</code></p></div></div></td><td><div><div><p>AUTO</p></div></div></td><td><div><div><p>Overrides parser type. Possible values are:</p></div><div><ul><li><p>AMF</p></li><li><p>RAML</p></li><li><p>AUTO</p></li></ul></div></div></td><td><div><div><p>1.3.7</p></div></div></td></tr><tr><td><div><div><p><code>apikit.multipart.size.limit</code></p></div></div></td><td><div><div><p>268435456</p></div></div></td><td><div><div><p>Limits the size of the multipart payload to be validated by throwing <code>InvalidFormParameterException</code> if the incoming multipart payload exceeds the limit (expressed in bytes).</p></div></div></td><td><div><div><p>1.8.0</p></div></div></td></tr><tr><td><div><div><p><code>fullDomain</code></p></div></div></td><td><div><div><p>localhost</p></div></div></td><td><div><div><p>Overrides the console URL.</p></div></div></td><td><div><div><p>1.1.15</p></div></div></td></tr></tbody></table>

## See Also

- [APIkit for REST](https://docs.mulesoft.com/apikit/latest/apikit-4-for-rest)

- [Building, Implementing, and Testing a REST API](https://docs.mulesoft.com/apikit/latest/apikit-4-implement-rest-api)

- [Converting a Mule Project to an APIkit Project](https://docs.mulesoft.com/apikit/latest/apikit-workflow-convert-existing)

- [APIkit for REST Error Handling Reference](https://docs.mulesoft.com/apikit/latest/apikit-error-handling-reference)

- [APIkit for REST Scaffolding Reference](https://docs.mulesoft.com/apikit/latest/apikit-4-scaffolding-reference)

- [APIkit Release Notes](https://docs.mulesoft.com/apikit/latest/apikit-release-notes)