Skip to main content

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:

  1. Role-Based Access Annotations
  2. File Input Annotation
  3. Unit Tests Annotation

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:

PropertyTypePurpose
namestringName of the role.
idstringUnique identifier of the role.
descriptionstringProvides more details about the role.
x-tagsList[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 overriden 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#

PropertyTypeExplanation
requestHTTP Request ObjectRequired This is where you define the request specific test data.
expectedResponseExpected HTTP Response ObjectRequired 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:

FlagsTypeDefault ValueExplanation
testNamestringRAML Method displayNameSpecifies the name of the test case to be generated.
testDescriptionstringRAML Method descriptionDescribes what the test case does.
testShouldPassbooleantrueShould this test pass? If false, the test would be required to fail in order to pass.
testEnabledbooleantrueIs 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.

PropertyTypeExplanation
methodEnum[string]Required This refers to the HTTP methods used for sending the request. Valid values include GET, POST, DELETE, PATCH, PUT.
uristringRequired Uniform resource identifier used to locate and identify a resource. May contain query parameters (/pets?pet-id=1) and template parameters (/pets/{pet-id}).
headersobjectKey-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.
bodystringThe 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.

PropertyTypeExplanation
statusCodestringRequired The expected HTTP status code of the response e.g. 200.
headersobjectKey-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.
bodystringThe expected body data of the response.

Additionally, a few configuration flags are also available:

FlagsTypeDefault ValueExplanation
allowExtraHeadersbooleantrueSpecifies whether headers other than those specified in the headers property of the Expected HTTP Response are allowed or not.
bodyMatchModeEnum [string]NONESpecifies 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.
arrayOrderedMatchingbooleanfalseIf true, testing of arrays will include order checking of the array elements as well.
arrayCheckCountbooleanfalseIf 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.