How to include an Extension Typed Fragment?


#1

I am new to RAML and modeling a large API that will have dozens of endpoints. I want to split the RAML up in to multiple files. The new RAML 1.0 Extension feature sounds perfect, but I can’t quite figure out how to use it. How or where do I include my RAML extension document in to my master RAML document? The spec has a few tantalizing hints, e.g.:

If a file begins with a RAML fragment identifier line, and the fragment identifier is neither Library nor Overlay nor Extension, the contents of the file after removal of the RAML fragment identifier line MUST be valid structurally according to the corresponding section of this RAML specification.

(emphasis mine) … but I can’t quite figure it out. Do I use the !include tag to reference the RAML extension document in the master RAML document? If so, where? I tried a few combinations but couldn’t get anything to work with API Designer.

If the RAML extension document isn’t referenced by the master RAML document, how does a RAML processor find it or even know it exists?

Thanks,
Roy


#2

Let me show you an example :wink:

This is my main RAML file that describes an API interface with all the capabilities. It does not include any implementation specific details like baseUri to make it more portable to different environments. The file is called librarybooks.raml

#%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:
    responses:
      200:
        body:
          application/json:
            type: array
            items:
              type: object
              properties:
                title: string
              example:
                title: RAML 1.0
/library:
  get:

Now I have another file that extends my interface description with implementation details specific to an environment. For example, let’s assume you promote your API from test to staging where you use a different baseUri. So you have the following file staging-env-ext.raml:

#%RAML 1.0 Extension

usage: The location of the staging instance.
masterRef: librarybooks.raml
baseUri: http://stg.my-api.com:8088

As you can see, that file has a key property that relates back to the main RAML librarybooks.raml by using the masterRef property. In this case both files are in the same folder.

Does that help?


#3

Not quite. If you want to use your extension with some RAML processing tool, e.x. a request validator, how do you configure it? How does it know about staging-env-ext.raml? What if there are multiple extension files?

Thanks,
Roy


#4

For comparison see RAML Library files - it’s clear to me how to incorporate them in my main RAML file - I use the uses property. What is the equivalent technique with Extensions? Or do I have completely the wrong idea?

Roy


#5

Hi @foreigner, the actually merge will be done by the parser/tooling not the spec. Currently there are two parser out that are still in beta, but the team around that is working hard to improve it.

The way how it will works afaik, is that you give the extension to the parser as a parameter. So not the parent RAML file as usual, but the extension. Multiple extensions are not yet supported I believe, but there are needs and I see the use cases here. For now, what you could do is chain some. So Master RAML -> Extension 1 -> Extension 2 where you give extension two to the parser.

You can test it and please let the developer know if you have any issues on the github repo. Feedback will help to improve the overall experience :wink:

Hope that makes some things more clear.


#6

Thanks for the response! However the spec specifically says that “chaining” like that is not permitted:

An overlay or extension document MUST contain a root-level masterRef property whose value MUST be the location of a valid RAML API definition (not another overlay or extension); the location is specified equivalently to the location specified in the value of an !include tag (as an absolute or relative path or as a URL).

Which beta parsers are you referring to? I’m using NodeJS so JavaScript would be ideal.

Thanks,
Roy


#7

Hi @foreigner, that seems to be a mistake and I will report it. We are currently working on the support of that inside the parser so that you have the following options:

  • have a method to get the full “aggregated” version (contains all nodes from extensions/overlays + master
  • have a method to get the merged version (extensions/overlays are merged into the master)
  • parameters for these methods should be a single overlays/extension as well as multiple

You can find the beta version for the JS parser here.


#8

That sounds great!

Thanks again,
Roy