Validation Against RAML Using MuleSoft APIkit Router

As a MuleSoft Certified Architect, Designer and Developer, I recently worked on API implementations for one of our clients using MuleSoft’s CloudHub. One common feature that we use across APIs implementations is to design an API using RESTful API Modeling Language (RAML) and validate incoming and outgoing message through the APIs against the defined RAML using the MuleSoft APIkit Router component.

In this article, we will demonstrate validating incoming messages to the APIs against the defined RAML using the MuleSoft APIkit Router component, and then conclude the scenario in which the APIkit Router doesn’t throw an exception, even passing undefined RAML parameters to the API in the request.

As we know, RAML contains API specifications like Resources, HTTP Methods, Traits, Query Parameters, URI Parameters, and JSON request and response schemas. In API implementation, Mule provides APIkit Router for routing messages, serializing responses, and validating payloads, headers, query-params, and URI-params against the RAML.

Let’s get started and define a resource in the RAML as below and create a Mule project to walk through how validation works in APIkit Router.

/policy:
  displayName: search policies by criteria
  post:
    queryParameters:
        operation:
          type: string
          required: true
          enum: [searchbycriteria]
        filter:
          type: string
          required: true
          enum: [basicdetails]

The below screen demonstrates APIkit Router configuration in the Mule project for validating and routing incoming Mule messages against the defined RAML.

Now let’s deploy the Mule project and make API calls. We will run three different test scenarios to see how the AKI kit Router validates incoming request against the RAML.

Invoking With All the Required Definitions

Let’s make an API call with all the required parameters as defined in the RAML defined above. We will see the incoming message gets validated successfully by the API Kit Router against the RAML and will give a proper success response.

Invoking With a Missing Required Query Parameter

Now let’s make an API call with a missing required query parameter “filter” as defined in the above RAML. Mule API Kit Router will throw the exception with the proper message regarding missing required “Query Parameter” defined in the RAML API definition.

ERROR 2017-10-16 15:53:05,247 [[PoliciesAPI].SDHTTP_Listener_Configuration.worker.01] org.mule.exception.CatchMessagingExceptionStrategy:

********************************************************************************

Message               : Required query parameter filter not specified

The above use cases show that APIkit Router validated the incoming Mule message to the APIs against the defined RAML specification, which seems pretty useful for an API implementation.

Now let’s take a close look at step 2 of the validation, where we received an exception when we hadn’t passed the required query parameter as defined in the RAML. What will happen when we pass some extra query parameters which are not defined in the RAML definition? Yes, this looks interesting.

Invoking With Extra (undefined) Query Parameters

Let’s pass one extra query parameter, “extraParam,” which is not defined in the above RAML specification, to the API. We will see that Mule APIkit Router validation will allow the API invocation and not throw any exceptions.

The API Kit Router validates the incoming request against the API RAML definition only for the parameters defined in the RAML specification and doesn’t validate any parameters which are not defined in the RAML specification. This is important to know for API designers and developers using MuleSoft for their API development.

Let’s share our knowledge to expand our MuleSoft community.

Thank you!