Originally published at: http://www.sitepoint.com/testing-apis-raml/
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
traits:
- secured:
description: Some requests require authentication
queryParameters:
accessToken:
displayName: Access Token
description: An access token is required for secure routes
required: true
- unsecured:
description: This is not secured
/account:
displayName: Account
get:
description: Get the currently authenticated user's account details.
is: [secured]
responses:
200:
body:
application/json:
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"
}
put:
description: Update the current user's account
/albums:
displayName: Albums
/{id}:
displayName: Album
uriParameters:
id:
description: Numeric ID which represents the album
/tracks:
displayName: Album Tracklisting
get:
responses:
200:
body:
application/json:
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.
and the only way to find out was through manual testing when my application breaks.