Faria Rehman April 19, 2017

Machine-readable API descriptions are key enablers of many modern service-oriented activities. Recently, some of the API description formats, including RAML and API Blueprint, have started supporting detailed request and response example objects. If you use such a format then a good news is that APIMatic’s code-gen engine now utilizes your example objects to automatically generate test cases for your API. That means if you generate an SDK using a RAML file that contains example objects, the SDK will come bundled with test cases for you to test your API, right away.

From RAML Example Objects to Test Cases

RAML Examples to Test Cases

Both RAML 0.8 and RAML 1.0 support example objects for various resource parameters (query parameters, URI parameters, body parameters, and form parameters). You can specify example value for these using the “example” property, whereas, in RAML 1.0, multiple examples can be specified. Similarly, example objects for the possible responses from a resource can also be specified using the “example/examples” property. The request example values and the expected response values can be utilized for testing purposes if you use APIMatic to import these API Description files. Example values for all required parameters must be present for successful generation of the test case for any particular resource.

Let’s take you through a brief journey of how you can specify various example values in RAML 0.8 and RAML 1.0 both. For better understanding, I will be using Calculator API for my illustration below.

Specifying Resource Parameter Values

RAML 0.8

The following code snippet has values to two different parameters. SUM value has been assigned to URI parameter “operation”, whereas 2 and 3 have been assigned to query parameters “x” and “y” respectively.

#%RAML 0.8
title: Calculator
version: 1.0
documentation:
- title: Calculator
content: Simple Calculator API
baseUri: https://examples.devapi.dream.press/apps/calculator
baseUriParameters: {}
/{operation}:
uriParameters:
operation:
description: ‘’
example: SUM
required: true
displayName: operation
enum:
- SUM
- SUBTRACT
- MULTIPLY
- DIVIDE
get:
displayName: Calculate
description: Calculates the expression based on the x and y operator
responses:
200:
description: Success
example: 5
queryParameters:
x:
description: ‘’
type: number
example: 2
required: true
displayName: x
y:
description: ‘’
type: number
example: 3
required: true
displayName: y

Once your parameter values have been specified, we can then automatically generate test cases out of them. Under RAML 0.8, if multiple values are provided, then APIMatic will utilize the first provided values by default.

RAML 1.0

Here, you have the ability to define multiple examples instead of a single example using the “examples” property. Each example object has a unique identifier that identifies the example. The “example” property is definitely valid in RAML 1.0 too but you can either use the “example” property or the “examples” property but not both. Observe the following snippet and see how “examples” property has been used to generate test case.

get:
description: Returns an organization entity.
responses:
201:
body:
application/json:
type: Org
examples:
acme:
name: Acme
softwareCorp:
value: # validate against the available facets for the map value of an example
name: Software Corp
address: 35 Central Street
value: Gold # validate against an instance of the `value` property

You can find more details on how to specify examples in RAML 1.0 at https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/#defining-examples-in-raml

Specifying Expected Response Headers

You can also specify response headers and their example values which can be utilized as the expected values for response headers in the generated test cases. Here an example value for header “Location” is “/invoices/45612”

post:
body:
type: Invoice
responses:
201:
headers:
Location:
example: /invoices/45612

Note to Self!

You don’t need to go through the hassle of specifying test cases for your API yourself. We will simply bring your example objects into use in order to create them. For more information, visit our website where complete documentation on the test case is already present for you to successfully run your test cases!