Over a million developers have joined DZone.

Testing Generic REST APIs with RAML

RAML's tester library is not just for testing Spring MVC controllers. You can also use it to test any REST API to check whether it adheres to a RAML specification.

· Integration Zone

Learn how API management supports better integration in Achieving Enterprise Agility with Microservices and API Management, brought to you in partnership with 3scale

In an earlier post I showed you how to create contract-driven REST services using RAML as a specification framework. However, the RAML tester library does not limit itself to being able to test Spring MVC controllers. You can also use it to test any REST API and check whether it adheres to a RAML specification.

The CheckingWebTarget class

The raml-tester library has a utility class that checks whether a REST call and the result from that call adhere to a given specification: CheckingWebTarget. You need a JAX-RS client API implementation for this to work, which is a generic client API for REST services. In my example, I’m using Jersey, which is the reference implementation, but you’re free to choose another implementation. This is the test:

public class RestApiTests {

    private static final RamlDefinition raml = RamlLoaders.fromClasspath(RestApiTests.class).load("helloworld.raml")
    private JerseyClient client = new JerseyClientBuilder().build();

    private CheckingWebTarget checking;

    public void createTarget() {
        checking = raml.createWebTarget(client.target("http://localhost"));

    public void testHelloEndpoint() {
        Assert.assertThat(checking.getLastReport(), RamlMatchers.hasNoViolations());

If for example you want to use RestEASY, you just replace the client declaration with this:

ResteasyClient client = new ResteasyClientBuilder().build();

The bare bones specification for this service is:

#%RAML 0.8
title: Hello world REST API
baseUri: http://localhost/
version: v1


This test will do a call to http://localhost/hello and check whether the call is valid according to the RAML specification. It will also check whether the result is valid, so for example the test will fail in this case if the result isn’t a JSON document, or when the service returns something else than a HTTP status code 200. If you want a more extensive example, I suggest trying the article I mentioned at the beginning of this article and try to implement it this way, using either Spring MVC or JAX-RS. Or if you want to try something different and quick, try doing it with Spark.

This system allows you to use test just about every REST API using a RAML specification independent of the mechanism you’re using to implement that REST API. If you’re looking into doing the same thing with API Blueprint or Swagger you’ll have to do a bit more work. API Blueprint does not have decent Java support (snowcrash is NOT decent support) and Swagger still really support a design-first methodology. At the moment, if you want test-by-contract-driven development, RAML at the moment is to only way to go in Javaland.

Unleash the power of your APIs with future-proof API management - Create your account and start your free trial today, brought to you in partnership with 3scale.


Published at DZone with permission of Lieven Doclo. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}