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
-