---
schema_version: "1"
id: aaaaebc10e3bb25109bb6c7c1686939423a4117ae4105cfee35733d1a6fb8bfb
title: Converting a Mule Project to an APIkit Project
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/apikit/latest/apikit-workflow-convert-existing.md
canonical_url: https://docs.mulesoft.com/apikit/latest/apikit-workflow-convert-existing
source_site: docs.mulesoft.com
content_type: documentation
content_hash: afedc8c5641673c31149f08b51b53d61f0adfa24c6afc47bfbdf8143159e239f
description: MuleSoft Documentation Site
release: 4.x
latest: true
---
# Converting a Mule Project to an APIkit Project

Convert Mule applications that implement HTTP and database logic into APIkit for REST projects so you expose the same behavior through a RAML or OpenAPI Specification (OAS) contract. Use the [manual approach](#manual-approach) to wrap APIkit Router around existing flows, or the [scaffolding approach](#scaffolding-approach) to rebuild flows from the API specification if regenerating structure matches your delivery plan. Balance complexity, risk, and how much of the flow graph you can refactor.

The walkthrough uses a sample Mule application that retrieves users from a database:

```xml
<mule>
    <http:listener-config name="HTTP_Listener_config">
		<http:listener-connection host="0.0.0.0" port="8081" />
	</http:listener-config>
	<db:config name="Database_Config">
		<db:my-sql-connection host="localhost" port="3306" user="admin" password="admin" database="usersdb" />
	</db:config>
	<flow name="GET-Users-FLOW">
		<http:listener config-ref="HTTP_Listener_config" path="/users"/>
		<db:select config-ref="Database_Config">
			<db:sql ><![CDATA[SELECT * FROM USERS]]></db:sql>
		</db:select>
	</flow>
	<flow name="GET-User-By-Id-FLOW">
		<http:listener config-ref="HTTP_Listener_config" path="/userById" />
		<db:select config-ref="Database_Config" >
			<db:sql ><![CDATA[SELECT * FROM USERS WHERE :userIdParameter == userID]]></db:sql>
			<db:input-parameters ><![CDATA[#[{userIdParameter: attributes.queryParams.id}]]]></db:input-parameters>
		</db:select>
	</flow>
</mule>
```

## [](#before-you-begin)Before You Begin

To define the API specification for your service, see [Design Your API Specification When Building, Implementing, and Testing a REST API](https://docs.mulesoft.com/apikit/latest/apikit-4-implement-rest-api#design-your-api-specification). To illustrate this example, create or copy the API specification and JSON example used in that workflow to the `/src/main/resources/api` folder.

## [](#manual-approach)Manual Approach

Follow these steps to configure a functional router for your existing flows manually.

### [](#step-1-create-a-main-flow)Step 1: Create a Main Flow

Within the APIkit project, create a main flow that serves as the entry point:

1. Drag the following components from the Mule palette to the canvas:
    
    - An **HTTP Listener** source as a flow source
    - An **APIkit Router** operation within the flow process
2. In the properties editor for **HTTP Listener** in **Connector Configuration**, select the existing **HTTP\_Listener\_Config**.
3. Specify a listener path for the APIkit router by entering `/api/` **in \*Path**.
4. In the properties editor for the APIkit router, in **Router Configuration**, click **Add** to create a new configuration.
    
    The **Global Element Properties** wizard appears.
5. In **API Definition**, select the `api/api.raml` path.
6. Accept the configuration.
7. Delete **HTTP Listener** from `GET-Users-FLOW`.
8. Delete **HTTP Listener** from `GET-User-By-Id-FLOW`.

```xml
<mule>
    <apikit:config outboundHeadersMapName="outboundHeadersMapName" httpStatusVarName="httpStatus" name="Router" api="api/api.raml" />
    <http:listener-config name="HTTP_Listener_config">
		<http:listener-connection host="0.0.0.0" port="8081" />
	</http:listener-config>
	<db:config name="Database_Config">
		<db:my-sql-connection host="localhost" port="3306" user="admin" password="admin" database="usersdb" />
	</db:config>
    <flow name="apiFlow">
		<http:listener config-ref="HTTP_Listener_config" path="/api/*"/>
		<apikit:router config-ref="Router"/>
	</flow>
	<flow name="GET-Users-FLOW">
		<db:select config-ref="Database_Config">
			<db:sql ><![CDATA[SELECT * FROM USERS]]></db:sql>
		</db:select>
	</flow>
	<flow name="GET-User-By-Id-FLOW">
		<db:select config-ref="Database_Config" >
			<db:sql ><![CDATA[SELECT * FROM USERS WHERE :userIdParameter == userID]]></db:sql>
			<db:input-parameters ><![CDATA[#[{userIdParameter: attributes.queryParams.id}]]]></db:input-parameters>
		</db:select>
	</flow>
</mule>
```

### [](#step-2-map-api-resources-and-actions-to-flows)Step 2: Map API Resources and Actions to Flows

By default, each APIkit flow adheres to a naming convention for routing purposes, characterized by the following pattern:

`action:\resource[:content-type][:config-name]`

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>action</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">HTTP method</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>resource</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">HTTP resource</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>content-type</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Payload content-type (optional)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>config-name</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">APIkit router configuration name (optional)</p></td>
</tr>
</tbody>
</table>

To retain the original flow names and map each API resource and action to them, override this behavior by following these steps:

1. Select **APIkit Router** to open the **Properties Editor**.
2. In **Router configuration**, click **Edit**.
    
    The **Global Element Properties** wizard appears.
3. In **Mappings**, click `Add` to create a new mapping configuration.
    
    The **New Mapping** dialog appears.
4. Use the drop-down to map the resources to actions.
    
    - In **Resource**, select `/users`.
    - In **Action**, select **Get**.
    - In **Flow**, select `GET-Users-FLOW`.
    - Click **OK**.
5. In **Mappings**, click **Add**.
    
    The **New Mapping** dialog appears.
6. Use the drop-down to map the resources to actions.
    
    - In **Resource**, select `/users/userbyid`.
    - In **Action**, select `Get`.
    - In **Flow**, select the flow that contains the get users action: `GET-User-By-Id-FLOW`.
    - Click **OK**.

```xml
<mule>
    <apikit:config outboundHeadersMapName="outboundHeadersMapName" httpStatusVarName="httpStatus" name="Router" api="api/api.raml" >
		<apikit:flow-mappings >
			<apikit:flow-mapping resource="/users" action="get" flow-ref="GET-Users-FLOW" />
			<apikit:flow-mapping resource="/users/userbyid" action="get" flow-ref="GET-User-By-Id-FLOW" />
		</apikit:flow-mappings>
	</apikit:config>
    <http:listener-config name="HTTP_Listener_config">
		<http:listener-connection host="0.0.0.0" port="8081" />
	</http:listener-config>
	<db:config name="Database_Config">
		<db:my-sql-connection host="localhost" port="3306" user="admin" password="admin" database="usersdb" />
	</db:config>
    <flow name="apiFlow">
		<http:listener config-ref="HTTP_Listener_config" path="/api/*"/>
		<apikit:router config-ref="Router"/>
	</flow>
	<flow name="GET-Users-FLOW">
		<db:select config-ref="Database_Config">
			<db:sql ><![CDATA[SELECT * FROM USERS]]></db:sql>
		</db:select>
	</flow>
	<flow name="GET-User-By-Id-FLOW">
		<db:select config-ref="Database_Config" >
			<db:sql ><![CDATA[SELECT * FROM USERS WHERE :userIdParameter == userID]]></db:sql>
			<db:input-parameters ><![CDATA[#[{userIdParameter: attributes.queryParams.id}]]]></db:input-parameters>
		</db:select>
	</flow>
</mule>
```

## [](#scaffolding-approach)Scaffolding Approach

Follow the process at [Before You Begin](#before-you-begin). When completed, include an alternative workflow for scaffolding your API specification.

With this approach, you get the APIkit router configuration, error handler, and console flow out of the box. You also get a flow that maps each resource.

### [](#step-1-scaffold-your-api-specification)Step 1: Scaffold Your API Specification

Scaffold your API to auto-generate the main, console, and resources flows:

1. In **Package Explorer**, right-click `/src/main/resources/api/api.raml`.
2. Select **Mule**.
3. Click **Generate Flows from Local REST API**.

A new XML file with the same name as the API is created. This file contains the scaffolded flows.

### [](#step-2-reference-flows)Step 2: Reference Flows

Do either of the following:

- Delete the scaffolded flows for each resource and map the original flows as described in [Step 2: Map API Resources and Actions to Flows](#step-2-map-api-resources-and-actions-to-flows).
- Remove all operations from the scaffolded flows and add a flow reference that contains the removed operations. By choosing this option, you introduce an additional layer of indirection because you reference all flows to the flow that has the operations, and such indirection can be inconvenient in some scenarios.

```xml
<mule>
...
    <flow name="get:\users\userbyid:api-config">
		<flow-ref name="GET-User-By-Id-FLOW"/>
    </flow>
    <flow name="get:\users:api-config">
		<flow-ref name="GET-Users-FLOW"/>
    </flow>
</mule>
```

- Transfer the content of the existing flows to the scaffolded flows that adhere to the routing naming convention. If the application is large, performing these modifications can be a laborious task.

```xml
<mule>
...
    <flow name="get:\users:api-config">
		<db:select config-ref="Database_Config">
			<db:sql ><![CDATA[SELECT * FROM USERS]]></db:sql>
		</db:select>
	</flow>
	<flow name="get:\users\userbyid:api-config">
		<db:select config-ref="Database_Config" >
			<db:sql ><![CDATA[SELECT * FROM USERS WHERE :userIdParameter == userID]]></db:sql>
			<db:input-parameters ><![CDATA[#[{userIdParameter: attributes.queryParams.id}]]]></db:input-parameters>
		</db:select>
	</flow>
</mule>
```

## [](#test-your-api)Test Your API

Now that your new project is set up, you are ready to [test](https://docs.mulesoft.com/apikit/latest/apikit-4-implement-rest-api#test-your-api-implementation) your API.

## [](#see-also)See Also

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