RAMLfications is a Python package that parses RAML and validates it based on the specification into Python objects.

A quick look at the library itself:

>>> 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.

What is RAML?

RAML stands for “RESTful API Modeling Language” and is described as “a simple and succinct way of describing practically-RESTful APIs”, extremely similar goal of Swagger. From raml.org’s site,

… you declare which version of RAML you are using, and then document basic characteristics of the API - the title, version, and baseURI.

RAML allows you to define patterns using traits, resourceTypes, and securitySchemes, and then use them within a API to minimize repetition.

Externalize those patterns, store them on the web, and import them with an !include.

Easily define resources and methods, then add as much detail as you want. Apply traits and other patterns, or add parameters and other details specific to each call.

A simple example of a RAML file (note: not Spotify’s actual RAML file):

#%RAML 0.8
title: Spotify Web API Demo - Simple Tree
version: v1
protocols: [ HTTPS ]
baseUri: https://api.spotify.com/{version}
mediaType: application/json

/tracks:
  displayName: several-tracks
  get:
    description: |
      [Get Several Tracks](https://developer.spotify.com/web-api/get-several-tracks/)
    queryParameters:
      ids:
        displayName: Spotify Track IDs
        type: string
        description: A comma-separated list of IDs
        required: true
        example: '7ouMYWpwJ422jRcDASZB7P,4VqPOruhp5EdPBeR92t6lQ,2takcwOaAZWiXQijPHIx7B'
  /{id}:
    displayName: track
    uriParameters:
      id:
        type: string
        displayName: Spotify Track ID
        example: 1zHlj4dQ8ZAtrayhuDDmkY
    get:
      description: |
        [Get a Track](https://developer.spotify.com/web-api/get-track/)
/users/{user_id}/playlists:
  uriParameters:
    user_id:
      displayName: User ID
      type: string
      description: The user's Spotify user ID.
      example: smedjan
  displayName: playlists
  get:
    description: |
      [Get a List of a User's Playlists](https://developer.spotify.com/web-api/get-list-users-playlists/)
  /{playlist_id}:
    put:
      description: |
        [Change a Playlist's Details](https://developer.spotify.com/web-api/change-playlist-details/)
      body:
        application/x-www-form-urlencoded:
          formParameters:
            name:
              displayName: Playlist Name
              description: Name of the new playlist
              type: string
              required: true
              example: Awesomesauce

Other examples can be found here, including Twitter, GitHub, Instagram, and LinkedIn.