APIMatic RAML Annotations
RAML v1.0 supports annotations that provide a mechanism to extend the API specification with metadata beyond the one supported by its official specification. APIMatic allows its users to extend their specification with annotations that can help configure output from APIMatic products such as API Transformer, Code Generation, Portal/Docs Generation etc.
Before you can use annotations in your API specification, you must also add a declaration for them in the root-level annotationTypes node as per the spec. For each annotation that we provide, this document will also provide you details about the declaration to be added.
The annotations offered by APIMatic are listed below:
Role-Based Access Annotations
APIMatic supports role-based API filtering. If you choose to filter your API by roles, the resulting portal will only contain documentation for those endpoints available to the specific role(s). It works by matching endpoint-level tags with tags associated with the available roles.
Roles can be defined in the RAML specification using the roles annotation in the root RAML object while method-level tags can be added through the x-tags annotation.
Annotation for Roles
To describe the possible list of roles for an API, the roles annotation can be used.
Annotation Type Declaration
To apply this annotation, you will first have to declare it under the annotationTypes root node as follows:
annotationTypes:
roles:
type: array
items:
type: object
properties:
id:
required: true
type: string
name:
required: false
type: string
description:
required: false
type: string
x-tags:
required: true
type: array
items:
type: string
Details of the properties available within a particular role object are:
| Property | Type | Purpose |
|---|---|---|
| name | string | Name of the role. |
| id | string | Unique identifier of the role. |
| description | string | Provides more details about the role. |
| x-tags | List[string] | List of String-valued tags associated with the role. |
Example Usage for Annotation
An example of applying roles annotation at the root RAML object is:
(roles):
- name: private
id: 2
description: private role
x-tags:
- pets
This means that role with id 2 will only have access to methods tagged as pets.
Annotation for Method level tags
Tags can be added to methods as a list of strings.
Annotation Type Declaration
To apply the x-tags annotation anywhere in your specification, you will first have to declare it under the annotationTypes root node as follows:
annotationTypes:
x-tags:
type: array
items:
type: string
Example Usage for Annotation
You can apply this annotation at method level as follows:
/pet/{id}:
get:
(x-tags):
- pets
displayName: Get pet by id
File Input Annotation
By default, file type request parameters are considered part of multipart/form-data in APIMatic. If, however, you are looking to send the file directly as part of the request body then this default behavior in APIMatic can be overridden by using the boolean sendFileInBody annotation at method level.
Annotation Type Declaration
To use this annotation, you will first have to declare it under the annotationTypes root node as follows:
annotationTypes:
sendFileInBody:
type: boolean
Example Usage for Annotation
The annotation can be applied at method level as shown below:
/file:
post:
(sendFileInBody): true
body:
binary/octet-stream:
Unit Tests Annotation
APIMatic auto-generates test cases from your RAML specification if it contains sufficient examples data to create one. When you generate an SDK, the test cases are converted to language-specific unit-tests that can easily let you test your SDKs. However, if you are interested in writing test cases yourself with real test data and within your RAML specification, then you can make use of our unit tests annotation. This annotation lets you easily add multiple test cases against each of your RAML v1.0 methods using the (unitTests) property. A detailed breakdown and usage examples for this annotation is given below.
Specifying Unit Tests Using Gavel Specification
The unit tests annotation makes use of Gavel specification to define the structure of a test case. Gavel is a tool from Apiary that is used to validate HTTP API calls based on comparisons between expected and real requests/response JSON objects. For our purposes, we have made use of only the HTTP Request and Expected HTTP Response JSON objects present in the gavel specification. Apart from these, we've extended the Gavel specification to add a few configuration options that are useful for test-case generation in APIMatic.
Unit Test Object
| Property | Type | Explanation |
|---|---|---|
| request | HTTP Request Object | Required This is where you define the request specific test data. |
| expectedResponse | Expected HTTP Response Object | Required This is where you define the response specific test data corresponding to the request data defined under the request property. |
A few optional configuration flags are also available:
| Flags | Type | Default Value | Explanation |
|---|---|---|---|
| testName | string | RAML Method displayName | Specifies the name of the test case to be generated. |
| testDescription | string | RAML Method description | Describes what the test case does. |
| testShouldPass | boolean | true | Should this test pass? If false, the test would be required to fail in order to pass. |
| testEnabled | boolean | true | Is this test enabled? Disabled tests are not generated and are not validated. Tests can be disabled in case they are outdated after an operation description is updated. |
HTTP Request Object
This object lets you describe your test request in more detail.
| Property | Type | Explanation |
|---|---|---|
| method | Enum[string] | Required This refers to the HTTP methods used for sending the request. Valid values include GET, POST, DELETE, PATCH, PUT. |
| uri | string | Required Uniform resource identifier used to locate and identify a resource. May contain query parameters (/pets?pet-id=1) and template parameters (/pets/{pet-id}). |
| headers | object | Key-value pairs containing information for request headers like the Content-Type, Accept, etc. Key should be the header name while the value would be the header test value. |
| body | string | The Request body can contain input parameters depending on the Content-Type specified in the headers. This is not applicable in case of method GET. |
Expected HTTP Response Object
This object lets you describe your expected response for the test request defined in the previous section.
| Property | Type | Explanation |
|---|---|---|
| statusCode | string | Required The expected HTTP status code of the response e.g. 200. |
| headers | object | Key-value pairs containing information for request headers like the Content-Type, Accept, etc. Key should be the header name while the value would be the expected value of the header. |
| body | string | The expected body data of the response. |
Additionally, a few configuration flags are also available:
| Flags | Type | Default Value | Explanation |
|---|---|---|---|
| allowExtraHeaders | boolean | true | Specifies whether headers other than those specified in the headers property of the Expected HTTP Response are allowed or not. |
| bodyMatchMode | Enum [string] | NONE | Specifies how body in the Expected HTTP Response is compared to the actual response body. More information on the Match Modes can be found at Body Match Modes. Valid values are NONE,RAW, KEYS, KEYSANDVALUES, NATIVE. |
| arrayOrderedMatching | boolean | false | If true, testing of arrays will include order checking of the array elements as well. |
| arrayCheckCount | boolean | false | If true, the arrays will be tested to see if they are equal in length. If both arrayOrderedMatching and arrayCheckCount are true, arrays will be strictly checked for equality i.e. their order as well as size must match. |
Annotation Type Declaration
In order to define unit tests in Raml v1.0 specification, you first have to define its type under annotationTypes root node as follows.
annotationTypes:
unitTests:
type: array
items:
type: object
properties:
testName:
required: false
type: string
testShouldPass:
required: false
type: boolean
testEnabled:
required: false
type: boolean
testDescription:
required: false
type: string
request:
required: true
type: object
properties:
method:
required: true
type: string
enum:
- GET
- PUT
- POST
- DELETE
- PATCH
uri:
required: true
type: string
body:
required: false
type: string
headers:
required: false
type: object
additionalProperties: true
expectedResponse:
required: true
type: object
properties:
allowExtraHeaders:
required: false
type: boolean
bodyMatchMode:
required: false
type: string
enum:
- NONE
- NATIVE
- KEYS
- KEYSANDVALUES
- RAW
arrayOrderedMatching:
required: false
type: boolean
arrayCheckCount:
required: false
type: boolean
matchResponseSchema:
required: false
type: boolean
statusCode:
required: true
type: string
statusMessage:
required: false
type: string
body:
required: false
type: string
Example Usage for Annotation
The unit tests annotation can be applied on any RAML Method object using the (unitTests) property which is an array of Unit Test objects as shown below:
/dummyResource:
post:
displayName: dummyName
(unitTests):
- request:
method: POST
uri: /message?id=4
headers:
user-agent: >-
curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0
OpenSSL/0.9.8x zlib/1.2.5
host: httpbin.org
accept: '*/*'
body: dummyBody
expectedResponse:
allowExtraHeaders: true
bodyMatchMode: KEYS
arrayOrderedMatching: false
arrayCheckCount: false
matchResponseSchema: true
statusCode: '200'
headers:
content-type: application/json
date: 'Wed, 03 Jul 1821 13:30:53 GMT'
server: gunicorn/0.17.4
content-length: '30'
connection: keep-alive
body: |
[{"from": "dFrom","to": ["d1","d2","d3"],"text": "description."}]
testName: getPetInfo
testEnabled: true
shouldPass: true
testDescription: Get pet information from its id
The information from these method/endpoint level unit tests is then converted to language-specific test cases upon SDK generation.