raml-validation-proxy

A lot of RESTful services using RESTful API Modeling Language to define their APIs. This service utilizes RESTful services test harness to verify if implementation follows API contract.

It creates http proxy to record requests and responses from oryginal service. After the tests json report can be generated.

It is built on Vert.x embedded server with Java 8 and Maven.

Roadmap

Following features are planned:

• Easier configuration.
• Integration with Maven Failsafe.
• Integration with JUnit.
• Gradle build.
• Request and response body verification.
• URL matching based on RAML parameters types.
• RAML parameters validation.
• Missing examples in RAML.
• RAML verification against wadl file.

How to start

Installing raml parser.

Download raml-java-parser.

Install in local repository:

mvn install

Starting proxy server.

mvn compile
mvn exec:java

Running your tests

By default proxy server listens on http://localhost:8081 and redirect calls to http://localhost:8080. Remember to set URL location to your RAML file (Check config section for details).

Showing report

Open in your browser:

• http://localhost:8081/raml-validation-proxy/raml_report.json Report with discrepancies with RAML and tests. See report section for detais.
• http://localhost:8081/raml-validation-proxy/proxy_log.json Recorded requests report.
• http://localhost:8081/raml-validation-proxy/raml_log.json Parsed RAML file report.
• http://localhost:8081/raml-validation-proxy/restart Restarts testing session. Reports are cleared.

Configuration

Application is looking for ramlvalidation_config.json file on the classpath.

Example configuration with default values:

{
   "target.host" : "localhost",
   "target.port" : 8080,
   "proxy.port" : 8081,
   "raml.resource" : "http://localhost:8080/service.raml",
   "ignored.resources" : [ "request.header.Host", "response.header.Date", "request.header.Accept", "request.header.Connection", "response.header.Server", "request.header.Content-Length", "response.header.Content-Length"
   ]
}

Report

What is checked:

• URLs,
• http methods,
• status codes,
• header names,
• header values (examples and defaults defined in RAML),
• query parameter names,
• query parameters values (examples and defaults defined in RAML).

In case checked value verification failed following messages are added to report:

• NOT_USED_IN_TEST : Defined in RAML file but no found in any request or response.
• NOT_DEFINED_IN_RAML : Found in request or response but not dfined in RAML file.

Example

{
  "/cars/{id}/resource": {
    "POST" : {
      "request.header.Count" : {
        "many" : "NOT_USED_IN_TEST"
      },
      "request.header.Accept" : "NOT_USED_IN_TEST",
      "response.status" : {
        "409" : "NOT_USED_IN_TEST"
      },
      "response.header.Content-Type" : "NOT_DEFINED_IN_RAML"
    }
  },
  "/cars" : "NOT_USED_IN_TEST",
  "/cars/123" : "NOT_DEFINED_IN_RAML"
}