Using RAML - First Impressions

Generated html documentation based on raml specification.

Introduction

I started working on a new interesting customer case. We have two teams and a need to agree on the API specification between the teams. It is a good practice to create the API contract between two teams using some dedicated API design tool. There are several such tools, the two most prominent being Swagger and RAML.

We decided to use RAML. In this blog post I describe first impressions using RAML.

Swagger

Swagger has been around quite long, initial release being already back in 2011. So, Swagger is an established tool and choosing Swagger is a good decision. Swagger’s sweet spot is to generate API documentation from the implementation. So, generating a new Swagger documentation can be integrated into the CI/CD cycle.

Nowadays Swagger is also known as OpenAPI Specification.

RAML

RAML has been around since 2013, so it is also an established tool. RAML is often used as a design tool, to document a to-be-implemented API. RAML can be used as a tool to provide an agreement on the API between two teams, just as we use it in our project. RAML can also be converted to OpenAPI specification (i.e. to Swagger).

Using RAML - First Impressions

Using RAML to document an API contract was quite pleasent. You can learn basic RAML stuff in some thirty minutes and start working with it. The documentation is good and there are a lot of examples. The following picture illustrates using RAML.

You use Yaml to create the API contract. Yaml is pretty concise and easy to use - therefore you can have a good overview regarding your API in a glance.

Inheritance.

You can follow DRY (don’t repeat yourself) principle using basic inheritance. Example. When you order pizza, you use type pizzaOrder:

  PizzaOrder:
    type: object
    properties:
      pizzaName: string
      name: string
      streetAddress: string
      postalCode: string
      postOffice: string
      mobileNumber: string

When the pizzaOrder is processed a pizza order with orderId is returned:

  PizzaOrderWithId:
    type: PizzaOrder
    properties:
      orderId: integer

I.e., you can inherit the PizzaOrder in the new type PizzaOrderWithId, and just add the new property to this new type: the orderId.

And then you can refer to these types in the API design:

  post:
      is: [ assets.authenticated ]
      description: Creates a new pizza order
      body: 
        application/json:
          type: assets.PizzaOrder      # <=========== HERE
          example: !include examples/pizzaorder/pizzaorder.json
      responses:
        200:
          body: 
            application/json:
              type: assets.PizzaOrderWithId      # <=========== AND HERE
              example: !include examples/pizzaorder/pizzaorderwithid.json

Json examples.

You can add various json examples in some examples directory and refer to those examples in your API design. Example:

pizzaorder.json:

{
  "pizzaName": "Americano",
  "name": "John Doe",
  "streetAddress": "Demo street 1",
  "postalCode": "00100",
  "postOffice": "Helsinki",
  "mobileNumber": "050 111 1111"
}

And then we refer to it in the API design:

  post:
      is: [ assets.authenticated ]
      description: Creates a new pizza order
      body: 
        application/json:
          type: assets.PizzaOrder
          example: !include examples/pizzaorder/pizzaorder.json     # <=========== HERE

… and in the HTML generated documentation we see:

Conclusions

Both Swagger and RAML are good API documentation tools. Their sweet spots might be a bit different - using Swagger to document an implemented API and using RAML to provide an agreement regarding an API contract in the design phase.

The writer is working at a major international IT corporation building cloud infrastructures and implementing applications on top of those infrastructures.

Kari Marttila

_{Kari Marttila’s Home Page in LinkedIn: https://www.linkedin.com/in/karimarttila/}