Usage

You can use ramlfications to parse and validate a RAML file with Python. With the command line, you can validate or visualize the RAML-defined API as a tree.

Parse

To parse a RAML file, include ramlfications in your project and call the parse function:

>>> import ramlfications
>>> RAML_FILE = "/path/to/my-api.raml"
>>> api = ramlfications.parse(RAML_FILE)
>>> api
RootNode(title='Example Web API')
>>> api.title
'My Foo API'
>>> api.version
'v1'
>>> api.security_schemes
[SecurityScheme(name='oauth_2_0')]
>>> oauth2 = api.security_schemes[0]
>>> oauth2.name
'oauth_2_0'
>>> oauth2.type
'OAuth 2.0'
>>> oauth2.settings.get("scopes")
['playlist-read-private', 'playlist-modify-public',..., 'user-read-email']
>>> oauth2.settings.get("accessTokenUri")
'https://accounts.foo.com/api/token'
>>> api.resources
[ResourceNode(method='get', path='/foo'), ResourceNode(method='put', path='/foo'), ..., ResourceNode(method='get', path='/foo/bar/{id}')]
>>> foo_bar = api.resources[-1]
>>> foo_bar.name
'/{id}'
>>> foo_bar.display_name
'fooBarID'
>>> foo_bar.absolute_uri
'https://api.foo.com/v1/foo/bar/{id}'
>>> foo_bar.uri_params
[URIParameter(name='id')]
>>> id_param = foo_bar.uri_params[0]
>>> id_param.required
True
>>> id_param.type
'string'
>>> id_param.example
'f00b@r1D'

You can pass in an optional config file to add additional values for certain parameters. Find out more within the Extended Usage:

>>> CONFIG_FILE = "/path/to/config.ini"
>>> api = ramlfications.parse(RAML_FILE, CONFIG_FILE)

For more complete understanding of what’s available when parsing a RAML file, check the Extended Usage or the API Definition.

Validate

Validation is according to the RAML Specification.

To validate a RAML file via the command line:

$ ramlfications validate /path/to/my-api.raml
Success! Valid RAML file: tests/data/examples/simple-tree.raml
$ ramlfications validate /path/to/invalid/no-title.raml
Error validating file /path/to/invalid/no-title.raml: RAML File does not define an API title.

To validate a RAML file with Python:

>>> from ramlfications import validate
>>> RAML_FILE = "/path/to/my-api.raml"
>>> validate(RAML_FILE)
>>>
>>> from ramlfications import validate
>>> RAML_FILE = "/path/to/invalid/no-title.raml"
>>> validate(RAML_FILE)
InvalidRootNodeError: RAML File does not define an API title.

Note

When using validate within Python (versus the command line utility), if the RAML file is valid, then nothing is returned. Only invalid files will return an exception.

If you have additionally supported items beyond the standard (e.g. protocols beyond HTTP/S), you can still validate your code by passing in your config file.

$ cat api.ini
[custom]
protocols = FTP
>>> from ramlfications import validate
>>> RAML_FILE = "/path/to/support-ftp-protocol.raml"
>>> CONFIG_FILE = "/path/to/api.ini"
>>> validate(RAML_FILE, CONFIG_FILE)
>>>

To learn more about ramlfications configuration including default/supported configuration, check out Configuration.

Tree

To visualize a tree output of a RAML file:

$ ramlfications tree /path/to/my-api.raml [-c|--color light/dark] [-v|vv|vvv] [-o|--output]

The least verbose option would show something like this:

$ ramlfications tree /path/to/my-api.raml
==========
My Foo API
==========
Base URI: https://api.foo.com/v1
|– /foo
|  – /bar
|  – /bar/{id}

And the most verbose:

$ ramlfications tree /path/to/my-api.raml -vvv
==========
My Foo API
==========
Base URI: https://api.foo.com/v1
|– /foo
|  ⌙ GET
|     Query Params
|      ⌙ q: Foo Query
|type: Item Type
|  – /bar
|    ⌙ GET
|       Query Params
|        ⌙ q: Bar Query
|type: item type
|  – /bar/{id}
|    ⌙ GET
|       URI Params
|        ⌙ id: ID of foo

Update

At the time of this release (Jun 5, 2015), the MIME media types that ramlfications supports can be found on GitHub.

However, you do have the ability to update your own setup with the latest-supported MIME media types as defined by the IANA. To do so:

$ ramlfications update

Note

If you are running Python version 2.7.8 or earlier, or Python version 3.4.2 or earlier, it is encouraged to have requests[all] installed in your environment. The command will still work without the package using the standard lib’s urllib2, but does not perform SSL certificate verification. Please see PEP 467 for more details.

Options and Arguments

The full usage is:

$ ramlfications [OPTIONS] COMMAND [ARGS]

The RAMLFILE is a file containing the RAML-defined API you’d like to work with.

Valid COMMAND s are the following:

validate RAMLFILE

Validate the RAML file according to the RAML Specification.

-c PATH, --config PATH

Additionally supported items beyond RAML spec.

update

Update RAMLfications’ supported MIME types from IANA.

tree RAMLFILE

Visualize the RAML file as a tree.

-c PATH, --config PATH

Additionally supported items beyond RAML spec.

-C <light|dark>, --color <light|dark>

Use a light color scheme for dark terminal backgrounds [DEFAULT], or dark color scheme for light backgrounds.

-o FILENAME, --output FILENAME

Save tree output to desired file

-v

Increase verbose output of the tree one level: adds the HTTP methods

-vv

Increase verbose output of the tree one level: adds the parameter names

-vvv

Increase verbose output of the tree one level: adds the parameter display name