RAMLfications – Python package to parse RAML

April 21, 2015 Published by Lynn Root

A few of us at Spotify are infatuated with RAML – a RESTful API Modeling Language described as “a simple and succinct way of describing practically-RESTful APIs”, extremely similar goal of Swagger.

I’m pleased to announce the initial release of RAMLfications, a Python package that parses RAML and validates it based on the specification into Python objects.

>>> from ramlfications import parse
>>> RAML_FILE = "/path/to/some/file.raml"
>>> api = parse(RAML_FILE)
>>> api.base_uri
'https://{subdomain}.example.com/v1/{communityPath}'
>>> api.resources
[ResourceNode(method='get', path='/widgets'),
 ResourceNode(method='get', path='/widgets/{id}'),
 ResourceNode(method='get', path='/widgets/{id}/gizmos'),
 ResourceNode(method='get', path='/thingys')]


>>> widget = api.resources[1]
>>> widget.name
'/{id}'
>>> widget.description
[Get a Widget](https://developer.example.com/widgets/)
>>> widget.description.html
u'<p><a href="https://developer.example.com/widgets/">Get a Widget</a></p>\n'
>>> widget.uri_params
[URIParameter(name='id'), URIParameter(name='communityPath')]

It’s available on PyPI with documentation on Read the Docs and code released under the Apache 2.0 license available on Spotify’s GitHub.

There are still some features that need to be implemented, and I am sure there are some bugs (please report them!), hence the initial beta release.

Why?

Last year, I built our developer API console, allowing folks a playground for understanding our Web APIs. The console first parses a RAML file that defines the API, then creates a set of forms based off of RAML, allowing a user-friendly way to directly interact with our Web API service.

One of the highlights of this console is the fact that none of the application itself (except for the HTML/CSS) is Spotify specific. This allows others to easily maintain the app, only editing our RAML file then restarting the service.

What’s next

I have plans to open source our API console that uses RAMLfications so others can easily create their own interactive environment.

My next hack project is to also write a documentation generator based off of RAML (of course, using ramlfications). Currently, RAML supports Markdown (and plaintext) for description and documentation elements within a RAML file. So using ramlfications, I’ll probably end up hacking on top of a static site generator. Stay tuned!


Tags: , , ,