RAML 1.0: review of innovations

RAML , the markup language used to describe the RESTful API, has already been written . In a discussion of the article on Habrahabr one of the readers noticed that RAML has not been updated for a long time, almost since the summer of 2014.

The RAML format has been significantly improved for several months. The new specification version 1.0 was published on the official website relatively recently, in early October 2015. Compared with the previous version (0.8), many changes and additions have been made to it. On the most significant innovations, we will describe in detail in this article.

')

Data types

The most important innovation in RAML 1.0 is data type support. Now in the introductory part of the document, you can describe in great detail all the data types with which the API works:

#%RAML 1.0 title: New API mediaType: application/json types: Person: type: object # properties: firstname: string lastname: string is_our_employee: boolean Document: type: object properties: Author title: string signing_date: date 

The data types defined in the specification can be used further in the description of response bodies, URI parameters, headers, and query parameters, for example:

 /documents/{documentId}: get: responses: 200: body: application/json: type: Document 

Examples: advanced features

In the documentation for any API, it is desirable to give as many examples as possible.
In RAML 1.0, examples can be added to any part of the document. Examples can be presented in both JSON and YAML formats:

 #%RAML 1.0 title: New API mediaType: application/json types: Person: type: object # properties: firstname: string lastname: string is_our_employee: boolean examples: { firstname: Alexander lastname: Ivanov is_our_employee: true } 

With examples, the description of the API becomes more understandable and intuitive.

Annotations

With the help of annotations, additional metadata can be inserted into the RAML specifications. This feature is useful when designing an API: in the annotation, you can add information that will be useful in the future (for testing, supplementing documentation, etc.).
Consider a simple example (taken from official documentation ):

 #%RAML 1.0 title: Illustrating annotations mediaType: application/json annotationTypes: experimental: /groups: (experimental): 

The introductory part of the document (the annotationTypes attribute) describes the general format of annotations. Next, one of the API endpoints is marked as experimental.

Annotations can also be used in more complex situations - for example, to describe test cases:

 #%RAML 1.0 title: Testing annotations mediaType: application/json annotationTypes: testCase: allowedTargets: [ Method ] allowMultiple: true usage: | Use this annotation to declare a test case. You may apply this annotation multiple times per location. properties: scenario: string setupScript?: string[] testScript: string[] expectedOutput?: string /documents: type: myResourceTypes.collection get: (testCase): scenario: No Documents setupScript: deleteAllDocuments testScript: getAllDocuments expectedOutput: [ ] (testCase): scenario: One Document setupScript: [ deleteAllDocuments, addDocs ] testScript: getAllDocuments expectedOutput: '[ { "id": 999, "author": "John Smith" } ]' (testCase): scenario: Multiple Documents setupScript: [ deleteAllDocuments, addDocs ] testScript: getAllDocuments expectedOutput: '[ { "id": 998, "author": "Bob Brown" }, { "id": 999, "name": "John Smith" } ]' 

Libraries

Another innovation RAML 1.0 - the library. A library is a file in which profiles, data types, and other information are placed in the introductory part of the document. Now in the new document you can not paint in detail the introductory part, but refer to the existing libraries. This practice resembles the connection of external libraries and modules in the program code.
Let us give an example of a library:

 #%RAML 1.0 Library #     libraries/files.raml usage: | Use to define some basic file-related constructs. types: File: properties: name: type: string length: type: integer traits: drm: headers: drm-key: resourceTypes: file: get: is: drm put: is: drm 

After the library is stored in a separate file, it can be accessed in the main specification file:

 #%RAML 1.0 title: Files API uses: files: !include libraries/files.raml resourceTypes: file: !include files-resource.raml /files: type: file 

Add-ins and extensions

Add-ins (overlays) and extensions (extensions) are intended to customize API descriptions — for example, when you need to create (and then regularly update and maintain) API documentation in several languages. This task is not as simple as it may seem at first glance. Most of the API documentation tools available cannot cope with this task without additional crutches.

With RAML 1.0, using add-ins, you can easily implement support for multilingual documentation. Imagine that we have documentation for the API in English, and we need to do French localization for it. English documentation is stored in the booklibrary.raml file. Let's give a small fragment:

 #%RAML 1.0 title: Book Library API documentation: - title: Introduction content: automated access to the books - title: Licensing content: Please respect the copyright on this book 

To add French localization, create an add-in file (overlay):

  #%RAML 1.0 Overlay usage: French localisation masterRef: booklibrary.raml documentation: - title: Introduction content: l'accès automatisé aux livres - title: licene content: Respectez les droits d'auteur svp 

This file includes only French translations; All descriptions of the methods and responses during generation will be taken from the main file.

With the help of extensions, you can create additional descriptions of methods and responses. This may be necessary to adapt the description of the API for different categories of users or for different use cases (for example, in a situation where the free version of the service is available to the base users, and the paid version users have an extended set of functions)

Consider the following fragments (examples are taken from here ):

Main file

 #%RAML 1.0 title: Book Library API documentation: - title: Introduction content: Automated access to books - title: Licensing content: Please respect copyrights on our books. /books: description: The collection of library books get: 

Expansion with a description of the functionality of the API for users with administrative rights

 #%RAML 1.0 Extension usage: Add administrative functionality masterRef: librarybooks.raml /books: post: description: Add a new book to the collection 

Extension for a custom version of the API available at the specified URL

 #%RAML 1.0 Extension usage: The location of the public instance of the Piedmont library API masterRef: librarybooks.raml baseUri: http://api.piedmont-library.com 

Conclusion

The innovations we have examined indicate that RAML is developing in the direction of a simple, but at the same time very flexible description language, which allows documenting even the most complex APIs.

I am also glad that new, more advanced tools for creating documentation for the API are appearing now. In the fall of 2015, MuleSoft (the main developer of RAML) released the API WorkBench plugin (see also the repository on GitHub ) for the Atom text editor - we recommend you pay attention. Let's hope that in the future this tool will develop successfully.

If you have already used RAML 1.0 to document the API, we invite you to share your experience. If it seems to you that we have forgotten to tell about some interesting innovation - write to us and we will definitely add it to the review.

If for one reason or another you cannot leave comments here - welcome to our corporate blog .