Testing APIs with RAML

Share this article

In a recent article I looked at RESTful API Modeling Language (RAML). I provided an overview of what RAML is all about, how to write it and some of its uses.

This time, I’m going to look at some of the ways in which you can use RAML for testing. We’ll start by using RAML to validate responses from an API. Then we’ll look at an approach you could take to mock an API server, using a RAML file to create mock HTTP responses.

Validating API Responses

First, let’s define a simple RAML file for a fictional API. I’ve left out some routes, but it will be enough to demonstrate the principles.

#%RAML 0.8
title: Albums
version: v1
baseUri: http://localhost:8000
  - secured:
      description: Some requests require authentication
          displayName: Access Token
          description: An access token is required for secure routes
          required: true
  - unsecured:
      description: This is not secured
  displayName: Account
    description: Get the currently authenticated user's account details.    
    is: [secured]
            schema: |
              { "$schema": "http://json-schema.org/schema#",
                "type": "object",
                "description": "A user",
                "properties": {
                  "id":  { 
                    "description": "Unique numeric ID for this user",
                    "type": "integer" 
                  "username":  { 
                    "description": "The user's username",
                    "type": "string" 
                  "email":  { 
                    "description": "The user's e-mail address",
                    "type": "string",
                    "format": "email" 
                  "twitter": {
                    "description": "User's Twitter screen name (without the leading @)",
                    "type": "string",
										"maxLength": 15
                "required": [ "id", "username" ]
            example: |
                "id": 12345678,
                "username": "joebloggs",
                "email": "joebloggs@example.com",                                
                "twitter": "joebloggs"
    description: Update the current user's account
  displayName: Albums
    displayName: Album
        description: Numeric ID which represents the album
      displayName: Album Tracklisting
                schema: |
                  { "$schema": "http://json-schema.org/schema#",
                    "type": "array",
                    "description": "An array of tracks",
                    "items": {
                      "id":  { 
                        "description": "Unique numeric ID for this track",
                        "type": "integer" 
                      "name":  { 
                        "description": "The name of the track",
                        "type": "string" 
                    "required": [ "id", "name" ]
                example: |
                      "id": 12345,
                      "name": "Dark & Long"
                      "id": 12346,
                      "name": "Mmm Skyscraper I Love You"

Notice we’ve defined a trait for secured routes, which expects an access token as a query parameter. We’ve defined a few available routes, and defined some JSON schemas to specify the format of the results. We’ve also included some example responses; these are what we’re going to use to generate mock responses.

Let’s create an application which we’ll use for both parts of this tutorial. You’ll find it on Github.

In this first part I’ll show how you can parse a RAML file, extract the schema for a given route and then use this to test against.

Create a project directory, and create the file test/fixture/api.raml with the contents above.

We’re going to use Guzzle to access the API, PHPUnit as a testing framework and this PHP-based RAML parser. So, create a composer.json to define these dependencies:

    "name": "sitepoint/raml-testing",
    "description": "A simple example of testing APIs against RAML definitions",
    "require": {
        "alecsammon/php-raml-parser": "dev-master",
        "guzzle/guzzle": "~3.9@dev",				
        "phpunit/phpunit": "~4.6@dev"
    "authors": [
            "name": "lukaswhite",
            "email": "hello@lukaswhite.com"
		"autoload": {
        "psr-0": {
          "Sitepoint\\": "src/"
    "minimum-stability": "dev"

Run composer install to download the required packages.

Now, let’s create a simple test which validates the response from an API. We’ll begin with a phpunit.xml file:

<?xml version="1.0" encoding="UTF-8"?>

        <testsuite name="PHP Raml Parser">

            <directory suffix=".php">./src</directory>


The PHP RAML Parser currently shows a deprecation error. To get around this, we’re setting convertErrorsToExceptions, convertNoticesToExceptions and convertWarningsToExceptions to false.

Let’s create a skeleton test class. Name this test/AccountTest.php, and start by defining the setUp() method:


class AccountTest extends PHPUnit_Framework_TestCase
     * @var \Raml\Parser
    private $parser;

    public function setUp()
        $parser = new \Raml\Parser();
        $this->api = $parser->parse(__DIR__.'/fixture/api.raml');

        $routes = $this->api->getResourcesAsUri()->getRoutes();

        $response = $routes['GET /account']['response']->getResponse(200);

        $this->schema = $response->getSchemaByType('application/json');


Here we’re parsing the RAML file, then extracting all of the defined routes. Next we’re pulling out the route identified by the string GET /account. From that, we’re extracting the definition of a successful response, and from that, we’re grabbing the JSON schema which defines the expected structure of the JSON response.

Now we can create a simple test which calls our endpoint, checks that we get back a 200 status, that the response format is JSON and that it validates against the schema.

/** @test */
public function shouldBeExpectedFormat()
	$accessToken = 'some-secret-token';

	$client = new \Guzzle\Http\Client();
	$request = $client->get($this->api->getBaseUri() . '/account', [
		'query' => [
			'accessToken' => $accessToken,
	$response = $client->send($request);
	// Check that we got a 200 status code
	$this->assertEquals( 200, $response->getStatusCode() );
	// Check that the response is JSON       
	$this->assertEquals( 'application/json', $response->getHeader('Content-Type')->__toString());
	// Check the JSON against the schema


It’s as simple as that; the RAML Parser provides a validator against our defined JSON schema.

There are a number of ways in which you could use RAML to test your APIs. As well as JSON schemas, RAML also supports XML schemas – so the principle of checking the results in XML format would be broadly similar. You could test that the appropriate status codes are returned, that the routes defined in your RAML all exist, and so on.

In the next section, we’ll look at using RAML to mock API responses.

Mocking an API using RAML

Another neat thing we can do with RAML is use it to mock an API. There are probably too many variations across different APIs to create a one-size-fits-all mocking class, so let’s build one which can be tweaked to your requirements.

What we’ll do is create three things:

  • A “response” class, which encapsulates standard HTTP response data, such as the status code and body
  • A class which uses RAML to respond to “URLs”
  • A simple “server” which you can run on a web server

To keep things simple, we’ll use the same code as in the previous section. We just need to add an additional dependency; FastRoute, a simple and fast routing component which we’ll use to determine the route we’re going to respond to. Add it to the require section of your composer.json file:

"nikic/fast-route": "~0.3.0"

Now, let’s create a really simple Response class; create this in src/Sitepoint/Response.php:

<?php namespace Sitepoint;

class Response {

	 * The HTTP status code
	 * @var integer
	public $status;

	 * The body of the response
	 * @var string
	public $body;

	 * An array of response headers
	 * @var array
	public $headers;

	 * Constructor
	 * @param integer $status The HTTP status code
	public function __construct($status = 200)
		$this->status = $status;
		$this->headers = [
			'Content-Type' => 'application/json'

	 * Sets the response body
	 * @param string $body
	public function setBody($body)
		$this->body = $body;
		$this->headers['Content-Length'] = strlen($body);


Nothing too complex here. Note that we’re going to mock an API which only “speaks” JSON, so we’re forcing the Content-Type to application/json.

Now let’s start a class which given an HTTP verb and path, will look through a RAML file to find a matching route, and return an appropriate response. We’ll do so by pulling out the example from the appropriate type of response. For the purposes of this component, that will always be a successful (status code 200) JSON response.

Create the file src/Sitepoint/RamlApiMock.php, and begin the class with the following:

<?php namespace Sitepoint;

class RamlApiMock {

	 * Constructor
	 * @param string $ramlFilepath Path to the RAML file to use
	public function __construct($ramlFilepath)
		// Create the RAML parser and parse the RAML file
		$parser = new \Raml\Parser();
		$api = $parser->parse($ramlFilepath);

		// Extract the routes
		$routes = $api->getResourcesAsUri()->getRoutes();
		$this->routes = $routes;

		// Iterate through the available routes and add them to the Router
		$this->dispatcher = \FastRoute\simpleDispatcher(function(\FastRoute\RouteCollector $r) use ($routes) {
			foreach ($routes as $route) {
				$r->addRoute($route['method'], $route['path'], $route['path']);


Let’s look at what we’re doing here.

As before, we’re parsing a RAML file. Then we’re extracting all of the available routes. Next we iterate through those, and add them to a collection which is compatible with the FastRoute component. Lucky for us, it uses the same format, so it’ll be able to translate the following:


to this:


The addRoute() method takes as its third argument the name of a function designed to handle the route. Ordinarily, you’d define separate functions to handle each route accordingly. However, since we’re going to handle all routes using the same code, we’re overriding this behaviour slightly, and rather than a function name we’re adding the path a second time. This way, we can extract the path in our handler to determine what response we need to send.

Let’s create a dispatch() method.

	 * Dispatch a route
	 * @param  string $method  The HTTP verb (GET, POST etc)
	 * @param  string $url     The URL
	 * @param  array  $data    An array of data (Note, not currently used)
	 * @param  array  $headers An array of headers (Note, not currently used)
	 * @return Response
	public function dispatch($method, $url, $data = array(), $headers = array())
		// Parse the URL
		$parsedUrl = parse_url($url);
		$path = $parsedUrl['path'];

		// Attempt to obtain a matching route
		$routeInfo = $this->dispatcher->dispatch($method, $path);

		// Analyse the route
		switch ($routeInfo[0]) {
			case \FastRoute\Dispatcher::NOT_FOUND:
				// Return a 404
				return new Response(404);				

			case \FastRoute\Dispatcher::METHOD_NOT_ALLOWED:
				// Method not allows (405)
				$allowedMethods = $routeInfo[1];				
				// Create the response...
				$response = new Response(405);
				// ...and set the Allow header
				$response->headers['Allow'] = implode(', ', $allowedMethods);
				return $response;

			case \FastRoute\Dispatcher::FOUND:
				$handler = $routeInfo[1];
				$vars = $routeInfo[2];
				$signature = sprintf('%s %s', $method, $handler);
				$route = $this->routes[$signature];

				// Get any query parameters
				if (isset($parsedUrl['query'])) {					
					parse_str($parsedUrl['query'], $queryParams);							
				} else {
					$queryParams = [];

				// Check the query parameters
				$errors = $this->checkQueryParameters($route, $queryParams);
				if (count($errors)) {
					$response = new Response(400);
					$response->setBody(json_encode(['errors' => $errors]));
					return $response;

				// If we get this far, is a successful response
				return $this->handleRoute($route, $vars);


So what’s going on here?

We start by parsing the URL and extracting the path, then use FastRoute to try and find a matching route.

The RouteCollection’s dispatch() method returns an array, with its first element telling us whether it’s a valid route, whether it’s a valid route but invalid method, or simply not found.

If we can’t find a matching route, we generate a 404 Not Found. If the method isn’t supported we generate a 405 Method Not Allowed, popping the allowed methods into the appropriate header.

The third case is where it gets interesting. We generate a “signature” by concatenating the method and path, so it looks something like this:

GET /account


GET /albums/{id}/tracks

We can then use that to grab the route definition from the $routes property, which you’ll recall we pulled out of our RAML file.

The next step is to create an array of query parameters, and then call a function which checks them – we’ll come to that particular function in a moment. Because different API’s can handle errors very differently, you may wish to modify this to suit your API – in this example I’m simply returning a 400 Bad Request, with the body containing a JSON representation of the specific validation errors.

At this point, you may wish to add some additional checks or validation. You could, for example, check whether the request has the appropriate security credentials supplied. We’re going to implement this via the required accessToken query parameter, which we’ve defined as a trait in the RAML file.

Finally, we call the handleRoute() method, passing the route definition and any URI parameters. Before we look at that, let’s return to our query parameters validation.

	 * Checks any query parameters
	 * @param  array 	$route  The current route definition, taken from RAML
	 * @param  array 	$params The query parameters
	 * @return boolean
	public function checkQueryParameters($route, $params)
		// Get this route's available query parameters
		$queryParameters = $route['response']->getQueryParameters();

		// Create an array to hold the errors
		$errors = [];

		if (count($queryParameters)) {

			foreach($queryParameters as $name => $param) {				

				// If the display name is set then great, we'll use that - otherwise we'll use
				// the name
				$displayName = (strlen($param->getDisplayName())) ? $param->getDisplayName() : $name;

				// If the parameter is required but not supplied, add an error
				if ($param->isRequired() && !isset($params[$name])) {
					$errors[$name] = sprintf('%s is required', $displayName);

				// Now check the format
				if (isset($params[$name])) {

					switch ($param->getType()) {
						case 'string':
							if (!is_string($params[$name])) {
								$errors[$name] = sprintf('%s must be a string');
						case 'number':
							if (!is_numeric($params[$name])) {
								$errors[$name] = sprintf('%s must be a number');
						case 'integer':
							if (!is_int($params[$name])) {
								$errors[$name] = sprintf('%s must be an integer');
						case 'boolean':
							if (!is_bool($params[$name])) {
								$errors[$name] = sprintf('%s must be a boolean');
						// date and file are omitted for brevity



		// Finally, return the errors
		return $errors;

This is pretty simple stuff – and note that I’ve left out certain parameter types to keep things simple – but this can be used to play around with query parameters, and reject requests where those parameters don’t fit the specifications laid out in our RAML file.

Finally, the handleRoute() function:

	 * Return a response for the given route
	 * @param  array 	$route  The current route definition, taken from RAML
	 * @param  array 	$vars   An optional array of URI parameters
	 * @return Response
	public function handleRoute($route, $vars)
		// Create a reponse
		$response = new Response(200);	

		// Return an example response, from the RAML

		// And return the result
		return $response;


What we’re doing here is extracting the example from the appropriate route, then returning it as a response with a status code of 200.

At this point, you could use the RamlApiMock in your unit tests. However, with a simple addition, we can also provide this mocking component as a web service, simply by wrapping a call to it with some simple routing logic.

To do this, create an index.php file with the following contents:

require_once 'vendor/autoload.php';

use Sitepoint\RamlApiMock;

// The RAML library is currently showing a deprecated error, so ignore it
error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE);

// Create the router
$router = new RamlApiMock('./test/fixture/api.raml');

// Handle the route
$response = $router->dispatch($_SERVER['REQUEST_METHOD'], $_SERVER['REQUEST_URI']);

// Set the HTTP response code

// Optionally set some response headers
if (count($response->headers)) {
	foreach ($response->headers as $name => $value) {
		header(sprintf('%s: %s', $name, $value));

// Print out the body of the response
print $response->body;

Hopefully this is pretty self-explanatory; we’re instantiating our “router”, handling the requested URL and method combination, then sending back the response with the appropriate status code and any headers.

Now run the server with the following:

php -S localhost:8000

Because APIs vary considerably, it’s likely you’ll need to modify this example to suit your implementation. Hopefully, it gives you enough to get started.


In this article I’ve looked at RAML in the context of testing and mocking APIs.

Since RAML provides an unambiguous and comprehensive statement of how an API should function, it’s very useful both for testing against and providing mock responses.

There’s much more you can do with RAML, and these examples only really touch the surface of how RAML can be used in testing, but hopefully I’ve provided you with a few ideas.

Frequently Asked Questions about Testing APIs with RAML

What is RAML and why is it important for API testing?

RAML, or RESTful API Modeling Language, is a YAML-based language used for describing HTTP-based APIs. It’s important for API testing because it provides a clear, concise way to describe API endpoints, methods, parameters, responses, and other details. This makes it easier for developers to understand the API’s structure and functionality, which in turn makes it easier to write effective tests. RAML also supports the use of schemas and examples, which can be used to validate responses and simulate API behavior during testing.

How do I start testing APIs with RAML?

To start testing APIs with RAML, you first need to create a RAML file that describes your API. This file should include details about the API’s resources, methods, parameters, and responses. Once you have a RAML file, you can use it to generate a collection of test cases using a tool like Postman or SoapUI. These test cases can then be run against your API to validate its behavior.

What tools can I use to validate my RAML file?

There are several tools available for validating RAML files. One popular option is the RAML API Designer, which provides a user-friendly interface for creating and validating RAML files. Another option is the RAML Console, which allows you to interact with your API directly from your RAML file. There are also several online validators available, such as the YAML Validator on Code Beautify.

How can I use RAML to simulate API behavior during testing?

RAML supports the use of examples, which can be used to simulate API behavior during testing. These examples can be included in your RAML file and used to generate mock responses when testing your API. This allows you to test how your application would handle different API responses without having to actually make requests to your API.

What are some best practices for testing APIs with RAML?

Some best practices for testing APIs with RAML include using schemas to validate responses, using examples to simulate API behavior, and using tools like Postman or SoapUI to generate and run test cases. It’s also important to keep your RAML file up-to-date as your API evolves, and to use version control to track changes to your RAML file.

Can I use RAML to test APIs that use different data formats?

Yes, RAML supports a variety of data formats, including JSON, XML, and others. This means you can use RAML to test APIs that use different data formats. You just need to specify the data format in your RAML file, and then use a tool like Postman or SoapUI to generate and run test cases that validate the API’s handling of that data format.

How can I use RAML to test APIs that require authentication?

RAML supports the description of various authentication methods, including Basic Authentication, OAuth, and others. You can specify the authentication method in your RAML file, and then use a tool like Postman or SoapUI to generate and run test cases that validate the API’s authentication behavior.

Can I use RAML to test APIs that use different HTTP methods?

Yes, RAML supports all standard HTTP methods, including GET, POST, PUT, DELETE, and others. This means you can use RAML to test APIs that use different HTTP methods. You just need to specify the HTTP method in your RAML file, and then use a tool like Postman or SoapUI to generate and run test cases that validate the API’s handling of that method.

How can I use RAML to test APIs that use different status codes?

RAML allows you to specify the expected status codes for each API response. This means you can use RAML to test APIs that use different status codes. You just need to specify the status codes in your RAML file, and then use a tool like Postman or SoapUI to generate and run test cases that validate the API’s handling of those status codes.

Can I use RAML to test APIs that use different request and response headers?

Yes, RAML allows you to specify the expected request and response headers for each API endpoint. This means you can use RAML to test APIs that use different headers. You just need to specify the headers in your RAML file, and then use a tool like Postman or SoapUI to generate and run test cases that validate the API’s handling of those headers.

Lukas WhiteLukas White
View Author

Lukas is a freelance web and mobile developer based in Manchester in the North of England. He's been developing in PHP since moving away from those early days in web development of using all manner of tools such as Java Server Pages, classic ASP and XML data islands, along with JavaScript - back when it really was JavaScript and Netscape ruled the roost. When he's not developing websites and mobile applications and complaining that this was all fields, Lukas likes to cook all manner of World foods.

Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week
Loading form