Contact Us 1-800-596-4880

Building, Implementing, and Testing a REST API

This workflow guides you through the process of designing, implementing, and testing a REST API.

For example purposes, this workflow uses the free online REST service {JSON} Placeholder, which provides mocked user information in JSON format.

Before You Begin

Ensure you have the following software installed:

  • Anypoint Studio 7.1.4 or later

  • Mule runtime engine 4.1.1 or later

Design Your API Specification

Design your API specification with API Designer from Design Center, with the API Specification Project tool from Anypoint Studio, or with a text editor of your choice:

  1. Create a JSON file including a list of users that serve as an example of what the service returns:

    [
      {
        "id": 1,
        "name": "Leanne Graham",
        "username": "Bret",
        "email": "Sincere@april.biz",
        "address": {
          "street": "Kulas Light",
          "suite": "Apt. 556",
          "city": "Gwenborough",
          "zipcode": "92998-3874",
          "geo": {
            "lat": "-37.3159",
            "lng": "81.1496"
          }
        },
        "phone": "1-770-736-8031 x56442",
        "website": "hildegard.org",
        "company": {
          "name": "Romaguera-Crona",
          "catchPhrase": "Multi-layered client-server neural-net",
          "bs": "harness real-time e-markets"
        }
      }
    ]
  2. Save it as user-example.json.

  3. Create a new blank file with the following API specification:

    #%RAML 1.0
    title: placeholder
    version: 1.0
    /users:
      get:
        description: Retrieve a list of all the users
        responses:
          200:
            body:
              application/json:
                example: !include user-example.json
      /userbyid:
        get:
          description: Get information about a particular user
          queryParameters:
            id:
              description: Specify the id of the user you want to retrieve
              type: integer
              required: false
              example: 3
          responses:
            200:
              body:
                application/json:
                  example: |
                    [
                      {
                        "id": 3,
                        "name": "Clementine Bauch",
                        "username": "Samantha",
                        "email": "Nathan@yesenia.net",
                        "address":
                          {
                            "street": "Douglas Extension",
                            "suite": "Suite 847",
                            "city": "McKenziehaven",
                            "zipcode": "59590-4157",
                            "geo": { "lat": "-68.6102", "lng": "-47.0653" },
                          },
                        "phone": "1-463-123-4447",
                        "website": "ramiro.info",
                        "company":
                          {
                            "name": "Romaguera-Jacobson",
                            "catchPhrase": "Face to face bifurcated interface",
                            "bs": "e-enable strategic applications",
                          }
                      }
                    ]
  4. Save it as api.raml.

  5. In Studio, select File > New > Mule Project.

  6. In Project Name, type the name of your Mule project.

    • If you are importing your API specification from Exchange, select Import a published API, click the plus icon, and select From Exchange.

      *Import a published API* highlighted when clicking on plus to select the From Exchange option
    • If you are importing your API specification from a local file in your file system, select Import RAML from Local File.

      *Import RAML from local file* highlighted in the API implementation section
    • If you are importing your API specification from Design Center, select Download RAML from Design Center.

      *Import from Design Center* highlighted in the API implementation section
  7. Select Scaffold flows from these API specifications if not already selected.

  8. Click Finish.

    APIkit generates the necessary flows based on the API specification you imported.

  9. Run your APIkit project by clicking Run > Run As > Mule Application.

Simulate API Calls

  1. In Anypoint Studio, locate the APIkit Consoles view and click Open console under the base point URL http://localhost:8081/console/.

    APIkit console tab displays the location of the basepoint URL in the window.
  2. Your default browser opens. The API Console shows the API summary and information about the project, such as the title, version, and supported protocols.

    API console version info
  3. In API Summary, select GET for the /users resource.

    It opens a detail page of the resource showing, among others, the expected JSON example for an HTTP 200 response.

    APIkit response
  4. In API Summary, expand /userbyid.

  5. Select GET for the /usersbyid resource.

  6. Click Try it to expand the view for sending a request.

    The API Console displays a section to add parameters and headers to try a request.

  7. Select Show optional parameters if not selected.

  8. Type 3 as a query parameter value for the id parameter and click Send.

    An HTTP 200 response confirms the successful request for the /usersbyid resource, which contains user information for the user with ID 3. This response also includes the body with a JSON example.

    Information for the user having id 3 highlighted

Add Business Logic to Your API Implementation

Modify the flows to return actual data from the JSON Placeholder service instead of the examples from the API.

  1. Drag a new Flow component from the Mule Palette.

  2. Rename the new flow as user_request_flow.

  3. Drag an HTTP Request component to the flow process.

  4. In the properties editor of Request, in General, set the following HTTP request options:

    • In Method, leave the default GET.

    • In Path, set to /users.

    • On Query Parameters, select Switch to expression mode and paste the following DataWeave script:

      output application/java
      ---
      if (not isEmpty(attributes.queryParams))
      {
      	id : attributes.queryParams.id
      }
      else
      {}
  5. Delete Transform Message component in get:\users:api-config and get:\users\userbyid:api-config flows.

  6. Drag one Flow Reference for each flow in replacement of the removed Transform Message components.

  7. In the properties editor of Flow Reference components, set flow name as user_request_flow.

  8. Save changes.

Test Your API Implementation

  1. In Package Explorer, right-click the project name and choose Run As > Mule Application.

  2. Open a browser and go to http://localhost:8081/api/users.

    The user information from the JSON Placeholder service is returned:

    [
       {
          "id": 1,
          "name": "Leanne Graham",
          "username": "Bret",
          "email": "Sincere@april.biz",
          "address": {
            "street": "Kulas Light",
            "suite": "Apt. 556",
            "city": "Gwenborough",
            "zipcode": "92998-3874",
            "geo": {
              "lat": "-37.3159",
              "lng": "81.1496"
    
        ...
        {
        "id": 10,
        "name": "Clementina DuBuque",
        "username": "Moriah.Stanton",
        "email": "Rey.Padberg@karina.biz",
        "address": {
          "street": "Kattie Turnpike",
          "suite": "Suite 198",
          "city": "Lebsackbury",
          "zipcode": "31428-2261",
          "geo": {
            "lat": "-38.2386",
            "lng": "57.2232"
          }
    ...
    ]
  3. Get information about the user having ID = 4 by going to http://localhost:8081/api/users/userbyid?id=4.

    [
      {
        "id": 4,
        "name": "Patricia Lebsack",
        "username": "Karianne",
        "email": "Julianne.OConner@kory.org",
        "address": {
          "street": "Hoeger Mall",
          "suite": "Apt. 692",
          "city": "South Elvis",
          "zipcode": "53919-4257",
          "geo": {
            "lat": "29.4572",
            "lng": "-164.2990"
          }
        },
        "phone": "493-170-9623 x156",
        "website": "kale.biz",
        "company": {
          "name": "Robel-Corkery",
          "catchPhrase": "Multi-tiered zero tolerance productivity",
          "bs": "transition cutting-edge web services"
        }
      }
    ]

Your REST API creation, implementation, and testing are complete.