The Power of RAML

This series focuses on three key areas of "meta-language" for Web APIs: API Description, API Discovery, and API Profiles. You’ll see articles covering all three of these important trends as well as interviews with some of the key personalities in this fast-moving space.

This InfoQ article is part of the series “Description, Discovery, and Profiles: The Next Level in Web APIs”. You can subscribe to receive notifications via RSS.

RAML, or the RESTful API Modeling Language, is a relatively new spec based on the YAML format- making it easily read by both humans and machines. But beyond creating a more easily understood spec (one that could be handed to the documentation team without worry), Uri Sarid, the creator of RAML wanted to push beyond our current understandings and create a way to model our APIs before even writing one line of code.

On his blog Untangled, Dr. Roy Fielding points out that we have a tendancy to design for the short term, or rather what is known, and what we are currently thinking about.

"Unfortunately, people are fairly good at short-term design, and usually awful at long-term design." – Roy Fielding, Creator of REST

The challenge with APIs is that they are usually intended to last, hopefully for years. After all, an API requires a substantial investment on the part of the developer, but also a substantial investment on part of the consumer – who relies on it and has to implement it. Uri started thinking about how to solve the challenge of long-term design with APIs in 2009. He wanted a tool that would allow you, in just a few lines, to model (or design) your API and then quickly generate a prototype that developers all around the world could try out and give you feedback. In 2013, his dream became a reality when RAML 0.8 was released.

Since then, interest in RAML has continued grow as companies large and small have realized the benefit of being able to design APIs in a human readable format, see exactly what their API will look like as they design it, and be able to create a live, functional example of the API that developers can make real calls against with just the click of a button.

(Click on the image to enlarge it)

Note

All of the RAML tools are open source and freely available att http://RAML.org/projects. My employer, MuleSoft, also offers freely hosted versions of these tools that you can use within their AnyPoint Platform for APIs.

The API Contract Design Cycle

However, simply creating a prototype was not enough. Working under the premise that an API is a contract not just between machines, but between a provider and a user, the MuleSoft API Contract Design Cycle was created:

This means that, after the creation of the design and creating a prototype, the developing company needs a way to share their API with others and solicit feedback. This valuable feedback would let them identify design flaws such as data or structural inconsistencies, as well as confusing aspects of their API. The identification of design issues in this stage is critical as, once you release an API, most cannot be fixed without breaking backwards compatibility which can hinder the use of your API.

Note

This cycle is also the basis behind Spec Driven Development.

API Console and API Notebook

To accomplish this, two more tools were developed: the API Console and the API Notebook. The API Console, similar to other API Consoles such as Mashery’s IO Docs and Swagger, provides both documentation and an interactive environment for developers to enter data and make calls. This means that developers, while prototyping the API, can quickly see what resources and methods are available and test them out for instant validation. At the same time, once your API is launched, you can provide interactive documentation (on top of your static documentation) to let developers try out and debug calls using a very simple interface.

The API Notebook, on the other hand, takes interactivity and exploration a step further by letting developers use JavaScript to call your (and other) APIs. In the API Notebook they are also able to manipulate the data to see how it would work in a real-world use case. This means developers can test your prototype for their use case without having to write anything more than a few lines of JavaScript.

For example, in the below screenshot users are able to connect to the Instagram API, authenticate using OAuth, and try searching for images with the tag “kitten;” being walked through each step along the way:

(Click on the image to enlarge it)

But what truly makes the API Notebook a powerful tool for RAML is that you can create use-cases for your consumers to work-through. What’s more, not only can you create these use case scenarios both for your prototype and for your API once it is launched into production, but your consumers can create their own Notebooks using markdown. This lets your consumers share bugs or their use cases both for feedback and support purposes, without having to share any proprietary code – or forcing you to work through their entire application.

This simple feature greatly reduces the effort your consumers have to put into getting their questions answered, while giving your support team reproducible errors that they can quickly identify without having to guess whether or not it is something being caused by the client’s code.

Once you have collected this feedback, you are able to fine-tune your design, and decide whether or not it is ready for production. The other advantage, as mentioned, is that when your API is ready to go live, you already have these two amazing tools for use in production!

To help you take your API live, you will find many other tools provided by the community including tools for generating the code for your API, as well as tools for testing your API, such as Abao. There are also numerous tools for documentation beyond just the API Console and the API Notebook, including RAML to HTML which generates a single HTML file (similar to the API console) for documentation, as well as RAML2HTML for PHP, a script that creates a full, multi-page documentation site:

(Click on the image to enlarge it)

This script is also completely customizable, letting you modify the overall template, and even content blocks to match your site exactly.

There are also numerous parsers for RAML, letting you easily integrate your Spec into your own custom applications, whether they are written in Ruby, PHP, JavaScript, .NET, Python, or Java.

Human Readable

Because RAML is designed to be human readable, getting started designing a new API, or defining a pre-existing API is easy. While you can create RAML in any editor, you’ll find that using the online API Designer or an IDE plugin such as the ones for Sublime or Visual Studio (both available at RAML.org/projects) make this process even easier by providing tooltips, autocomplete, and real-time validation as you go.

To get started, just begin your RAML file like so:

#%RAML 0.8
title: This is My API
baseUri: http://api.domain.com
version: 1

In the above we are first declaring that this is a RAML spec, using RAML version 0.8 (version 1 is set to be released soon), declaring the title of our API, the base URI for our API, and what version our API is (in this case, version 1).

Declaring resources in RAML is as simple as /resourceName, and methods are likewise as quick and simple to add just by referencing the HTTP verb:

#%RAML 0.8
title: This is My API
baseUri: http://api.domain.com
version: 1

/resource1:
  get:
    description: This gets the collection of resource1
  post:
    description:  This adds a new item to the collection

RAML offers you the ability to host multiple responses, returning back different status codes, headers, and bodies.  For example:

#%RAML 0.8
title: This is My API
baseUri: http://api.domain.com
version: 1

/resource1:
  get:
    responses:
      200:
        headers:
          cache-control:
            example: |
              public, no-cache, no-store

        body:
          application/json:
            example: |
              {"name":"Michael Stowe"}
          application/xml:
            example: |
              <name>Michael Stowe</name>
      400:
        #...
      401:
        #...

RAML also has numerous other features built in, letting you fully define your API with schemas and parameters.  It also allows for resource nesting (similar to how Saas lets you next CSS), file includes (letting you pull in multiple files to keep your spec easy to read and organized), and even the setting of variables or properties for consistent use throughout the Spec.

For example, you could take advantage of these features in your spec like so:

#%RAML 0.8
title: This is My API
baseUri: http://api.domain.com
version: 1

/resource1:
  get:
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                  "type": "object",
                  "$schema": "http://json-schema.org/draft-03/schema",
                  "id": "http://jsonschema.net",
                  "required": true,
                  "properties": {
                    "firstName": {
                      "type": "string",
                      "required": true
                    },
                    "lastName": {
                      "type": "string",
                      "required": true,
                      "minLength": 3,
                      "maxLength": 36
                    }
                  }
              }

  /sub-resource:
    get:
      queryParameters:
        firstName:
          description: "the user’s first name"
          example: John
          required: true
          type: string

Developer Friendly

Beyond the simple format and tooling available for RAML, developers are able to incorporate coding best practices such as utilizing patterns and reusing code. This not only greatly reduces the work one has to do but also helps keep the API uniform across resources and methods. While you can always extract schemas to keep your spec organized or pull in schemas, examples, and other RAML snippets using the "!include" command, RAML offers two additional useful and unique templating features: traits and resourceTypes.

Defining Common Atributes with traits

RAML’s traits allow you to define common attributes (or traits) for methods (GET, PUT, POST, PATCH, DELETE, etc) such as whether or not they are filterable, searchable, or pageable.

By creating a trait, you are actually creating a template that accepts parameters to provide the attributes to the method in a couple lines, while providing as much flexibility and customization to that trait as you need:

traits:
-searchable:
  queryParameters:
  query:
  description: |
    JSON array [{"field1","value1","operator1"},…] <<description>
  example: |
    <<example>>

/people:
  get:
    is: [searchable: {description: "search by location name", example: "[\"firstName\"\,\"Michael\",\"like\"]"}]

Templating Resources with ResourceTypes

Also, resourceTypes, like traits, allow you to setup templates for the resources themselves, letting you call in common methods and responses. For example, for a Collection you might commonly use POST and GET, and have the common 200, 201, and 400 status codes. Rather than having to enter these each and every time for every resource you have, by declaring them as a resourceType you can call them in just two lines.

resourceTypes:
- collection:
    description: Collection of available <<resourcePathName>>
    get:
      description: Get a list of <<resourcePathName>>.
      responses:
        200:
          body:
            application/json:
              example: |
                <<responseVariable>>
        400:
          #...
        401:
          #...

/people:
  type:
    collection:
      responseVariable: |
        {
         "name" : "Michael Stowe",
         "company" : "MuleSoft",
        }

You can even setup optional methods within resourceTypes by adding a question mark (?) to the method. Then this method will only be included in the actual resource if it declares it, granting you even more flexibility.

Note

RAML lets you create as many resourceTypes and traits as necessary. However, should you find yourself creating more than two resourceTypes (collection and item), you may want to evaluate your API to ensure you are remaining consistent in how it is being used. You can learn more in the RAML 200 Tutorial.

Auto-Generate SDKs

RAML also opens up other tooling to save developers valuable time and resources, such as the ability to auto-generate SDKs in multiple languages through providers like APImatic.io. Instead of having to manually write these SDKs, or having to rely on the community to keep them up to date, APImatic.io lets you import your RAML spec and creates SDKs for Java, Python, PHP, Ruby, AngularJS, iOS, and Windows.

Beyond the Code

RAML is emerging as one of the leading API specs, alongside of Swagger and API Blueprint, and today is supported by more and more API solutions providers (both management and tooling).

In order to keep things moving forward, and to ensure the integrity of the spec, along with the creation of RAML in 2013, an API industry driven working group was created. The working group is responsible for the direction of RAML, ensuring that it continues to follow best practices and meet industry needs. Today the group is made up of representatives from MuleSoft, AngularJS, Intuit, Airware, PayPal, API Science, Akana, and Cisco.

With RAML just over a year old now, work is underway on version 1.0, with the goal to provide even more functionality, and meet even more of the industry’s needs — while pushing for API best practices. Of course, challenges remain, including how to define/ describe hypermedia, something that has alluded all of the major specs. Challenges where you are able to help.

That’s the great thing about an open source community, there is always room for ideas. And anyone can get involved by visiting RAML.org, and contributing their own tools or forking the spec on GitHub. After all, the power of RAML isn’t in just what its accomplished so far today — the ability to have a single source of truth to visually design, prototype, build, share, and document your API — but how it will continue to impact the future.

About the Author

Michael Stowe, a RAML enthusiast, has over 10 years experience building applications for different use cases including law enforcement, the medical field, non-profits, industrial companies, and has contributed to several open source projects. He now works as a Developer Relations Manager at MuleSoft, where he has spoken on RAML and API Design at multiple conferences including API Con, API Strategy and Design, and API World. Look for Michael’s new book on REST API Design coming soon, and follow @mikegstowe on Twitter to stay up to date with his latest posts. You can also view past talks and read his thoughts of his at http://www.mikestowe.com

This series focuses on three key areas of "meta-language" for Web APIs: API Description, API Discovery, and API Profiles. You’ll see articles covering all three of these important trends as well as interviews with some of the key personalities in this fast-moving space.

This InfoQ article is part of the series “Description, Discovery, and Profiles: The Next Level in Web APIs”. You can subscribe to receive notifications via RSS.