The new version of the RAML API definition language is here, as announced on the RAML blog by Nial Darbey. In this article, we’ll briefly cover the novelties offered by this new release, and give you useful pointers to dig further.
Mike Stowe, Developer Relations Manager at MuleSoft, gave a presentation about RAML 1.0 and published his slide deck on SlideShare.
So what’s new?
RAML 1.0 brings a nice and elegant new YAML based syntax for defining data models, in addition to the existing JSON schema support. Here’s an example modeling a Product entity:
Product: properties: id: number name: string price: number tags: string dimensions: properties: length: number width: number height: number warehouseLocation: string
Data models can be imported in other models, to compose them more easily, can be used as schemas or examples, in path variables, query parameters, headers…, and can be stored in external libraries and be namespaced.
Your data models, resourceTypes, traits, schemas, examples can all be stored in a reusable library. This is convenient when you want to share common elements between different APIs in the same project or company. Importing those resources can be done through a namespace, giving you the freedom to pick up what you need or ignore what you don’t need.
In your RAML spec, you’ll write for example:
uses: Songs: !include libraries/songs.raml
Songs will be your namespace, and then later on reference the Song model with:
When developing APIs, you certainly develop and test it in different environments before moving it to production. How do you deal with those different contexts? How do you change the host URL for example? With RAML 1.0, overlays come to the rescue, to override or complement existing values of your specification.
Your original RAML specification might look like the following:
#RAML 1.0 title: Book library API documentation: - title: Introduction content: Automated access to data - title: Licensing content: Please respect copyright on our books /books: description: The collection of library books get: responses: 200: body: application/json: type: array items: type: object properties: title: string example: title: RAML 1.0 …
And the overlay will define or override the author, title, description, and more, with the following:
#RAML 1.0 Overlay uses: extLib: !include lib.raml masterRef: librarybooks.raml (extlib.info): author: Christian Vogel title: Example API description: Cool API termsOfServiceUrl: http://raml.org/terms/ contact: firstname.lastname@example.org license: MIT
Instead of vendor extensions in Swagger / Open API Specs, RAML 1.0 introduces “annotations”. Annotations are just new properties in your specification. Additionally, you can combine libraries and overlays to keep annotations separate from your main definition, so they don’t clutter your main definition and can be kept as an external concern.
- formParameters are replaced with properties.
- Sequences and composition from global definitions are removed in favor of fragments and libraries.
- The date type has been refined with more specialized types.
- The OAuth 2 authorization grants have been renamed to match the RFC.
- Support for inline anonymous definitions has been removed for resource types, traits and security schemes.
- Optional nodes are now limited to methods in resource types only.
- No support for baseUriParameters on root-level nodes.
If you want to discover RAML, don’t miss this interesting RAML tutorial which guides you through writing a sample API definition. Also have a look at Restlet Studio and APISpark capabilities for importing and exporting RAML definitions (there’s also a screencast). Soon, you’ll be able to use RAML 1.0 in our products as well when RAML 1.0 is ready!