Nav

How to Implement and Test an API

Let’s use Anypoint Studio to create, change, mock, and test an API using MUnit to make a unit testing suite for your application.

Jump ahead to the How to Sync an API between Anypoint Studio design environment and your Anypoint Platform instance.

Prerequisites

To create a Studio project for the example T-Shirt API on Anypoint Platform, you first need to set up the t.shirt.raml RAML definition according to the instructions in How to Design an API

This tutorial showcases the basic usage of Studio for working with an API deployed in Anypoint Platform.
If this is your first time using Studio, we also recommend you to take a quick look at our Basic Studio Tutorial for a more detailed explanation of each tool and view within Studio.

Create a Mule App Project Based on a RAML Definition

Start by creating a Mule project in Studio. We use APIkit to process an existing API backed by RAML:

  1. Click File > New > Mule Project to create a project, and set the field values in the new project wizard:

    • Type an arbitrary name for the project, for example t-shirt.

    • Select a Mule runtime version, for example Mule 3.8.0 EE.

    • Check Add APIkit components.

    • In API Definition, click the browse …​ button, and select Anypoint Platform.

      walk-new-proj

      The "Browse API Manager for APIs" dialog appears.

  2. Click Add Credentials.

    The Anypoint Platform Sign In dialog appears.

    walk-browse-api-mgr

  3. Enter your user name and password, and click Sign In.

    The names and versions of your APIs in your Anypoint Platform organization, for example the Enterprises organization appear. If you belong to multiple organizations, use the drop-down located above the list of APIs to select your APIs in other organizations.

    walk-browse-api-mgr2

  4. Select the API you want to use in Studio, T-Shirt Ordering Service in this example. Click OK. Click Finish.

    The t-shirt.xml file appears in the src/main/app folder of the Package Explorer. The api-main flow appears at the top of the canvas and contains the APIkit Router. Below the main flow, are the other flows defined by the RAML—​one for each resource/method pairing defined within the RAML spec. Do not rename these flows.

    Take a moment to see all the default views that are loaded once the SOAP application is imported.

    studio6-project-open

    If you are familiar with Anypoint Studio Visual Editor, you notice a new view loaded next to the Mule Palette.

    This is the API Sync view, which allows you to synchronize your changes with Anypoint Platform and to download all updates from the Anypoint Platform to your Studio instance.

    The specific usage for this example is also covered in our sync an API quickstart.

    The project creation process also adds a Reference Exception Strategy to handle all possible errors.

  5. Select Run project t-shirt from the context menu.

    The Console below the canvas shows the output of building and deploying the project. The APIkit Consoles tab contains a mockup of the API operations identical to the mockup you used earlier in the API Designer.

apikit-console-resources

Use the mocking service and enter the email address and an orderId as a query parameter to retrieve a particular order.

In response, you receive a status 200: success!

The regular expression used to define the pattern of each query parameter might cause the APIKit to flag those fields as Invalid pattern.
If this happens, click on Force GET to see the results.

Using MUnit for Unit Testing

A unit test consists of verifying that a single unit of code works as expected. Use MUnit to ensure the core functions of your application behave as you intended.

MUnit is the Mule application testing framework that allows you to build automated tests for your integrations and APIs. We recommend integrating MUnit into your continuous deployment environment.

In this particular example, we focus on verifying the statuses and payloads returned by your APIKit router configuration following your file.raml specs.

Later on, you can choose to automate each test to run before you deploy the application to guarantee the app works according to your design.

After you install MUnit as indicated below, work with its integrated automatic test creator to build the necessary tests for a RAML-based application.

Install MUnit

MUnit comes bundled with Studio 5.4.0 and later. If you are running an older Studio version, you first need to install MUnit.

  1. Go to Help / Install New Software…​

  2. Click the Add…​ button.

  3. Set the Name: field to MUnit Update Site and the Location: field to http://studio.mulesoft.org/beta/r5/munit

  4. Check Munit and Munit Tools for Mule, and click Next to complete the installation.

  5. After installation, restart Anypoint Studio.

MUnit is fully integrated with Anypoint Studio, allowing you to design your tests the same way you would design a Mule application in Studio.

It allows you to automatically generate a test suite based on the RAML definition used by your APIKit router. In this case, MUnit creates a test for every flow created in your Mule application with the purpose of verifying the expected http status code and response payload of every flow.

Generate an MUnit Test Suite

In order to generate this test suite, first make sure you have no Mule applications running from Studio.
Right click your APIKit router component, navigate to the MUnit submenu and select Create t-shirt.xml Suite for RAML

generate_test_from_raml

MUnit creates a test for each flow in your application and returns the following MUnit test suite:

generated_munit_suite_from_raml


    
            
         
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<spring:beans>
    <spring:import resource="classpath:t-shirt.xml" />
</spring:beans>
<munit:config mock-connectors="false" mock-inbounds="false" />
<http:request-config name="HTTP_Request_Configuration" host="localhost" port="8081" basePath="/api" />
<munit:test name="get:/products:t-shirt-config-200-application/json-FlowTest" description="Verifying functionality of [get:/products:t-shirt-config-200-application/json]">
    <http:request config-ref="HTTP_Request_Configuration" method="GET" path="/products" />
    <object-to-string-transformer doc:name="http response to string" />
    <munit:assert-true message="The HTTP Status code is not correct!" condition="#[messageInboundProperty('http.status').is(eq(200))]" doc:name="assert that - http.status eq 200" />
    <munit:assert-on-equals message="The response payload is not correct!" expectedValue="#['[
  {
    "productCode": "TS",
    "size": "S",
    "description": "Small T-shirt",
    "count": 30
  },
  {
    "productCode": "TS",
    "size": "M",
    "description": "Medium T-shirt",
    "count": 22
  }
]']" actualValue="#[payload]" doc:name="assert that - payload is as expected" />
</munit:test>
<munit:test name="get:/orders/status:t-shirt-config-200-application/json-FlowTest" description="Verifying functionality of [get:/orders/status:t-shirt-config-200-application/json]">
    <set-variable variableName="orderId" value="#['4321']" doc:name="orderId" />
    <http:request config-ref="HTTP_Request_Configuration" method="GET" path="/orders/status">
        <http:request-builder>
            <http:query-param paramName="orderId" value="4321" />
        </http:request-builder>
    </http:request>
    <object-to-string-transformer doc:name="http response to string" />
    <munit:assert-true message="The HTTP Status code is not correct!" condition="#[messageInboundProperty('http.status').is(eq(200))]" doc:name="assert that - http.status eq 200" />
    <munit:assert-on-equals message="The response payload is not correct!" expectedValue="#['{
  "orderId": "4321",
  "status": "Delivered",
  "size": "M"
}']" actualValue="#[payload]" doc:name="assert that - payload is as expected" />
</munit:test>

It is important to define the purpose of your test. This automatic test validates the payloads and http response codes returned by your exposed APIKit endpoint.
In other words, you are making sure that a GET request receives a 200 status code response, and that the payload of this response is the one you are expecting.

To test this application, right click any blank space in your Test Suite workspace and select Run MUnit Suite:
run-test-suite

The result of every test is shown in the MUnit view in Anypoint Studio:
test-suite-result