API Definition

Main functions

The following three functions are meant for you to use primarily when parsing a RAML file/string.

ramlfications.parse(raml, config_file=None)

Module helper function to parse a RAML File. First loads the RAML file with loader.RAMLLoader then parses with parser.parse_raml() to return a raml.RAMLRoot object.

Parameters:
  • raml – Either string path to the RAML file, a file object, or a string representation of RAML.
  • config_file (str) – String path to desired config file, if any.
Returns:

parsed API

Return type:

RAMLRoot

Raises:
  • LoadRAMLError – If error occurred trying to load the RAML file (see loader.RAMLLoader)
  • RAMLParserError – If error occurred during parsing of RAML file (see raml.RAMLRoot)
  • InvalidRamlFileError – RAML file is invalid according to RAML specification.
ramlfications.load(raml_file)

Module helper function to load a RAML File using loader.RAMLLoader.

Parameters:raml_file (str) – String path to RAML file
Returns:loaded RAML
Return type:dict
Raises LoadRAMLError:
 If error occurred trying to load the RAML file
ramlfications.loads(raml_string)

Module helper function to load a RAML File using loader.RAMLLoader.

Parameters:raml_string (str) – String of RAML data
Returns:loaded RAML
Return type:dict
Raises LoadRAMLError:
 If error occurred trying to load the RAML file
ramlfications.validate(raml, config_file=None)

Module helper function to validate a RAML File. First loads the RAML file with loader.RAMLLoader then validates with validate.validate_raml().

Parameters:
  • raml (str) – Either string path to the RAML file, a file object, or a string representation of RAML.
  • config_file (str) – String path to desired config file, if any.
Returns:

No return value if successful

Raises:
  • LoadRAMLError – If error occurred trying to load the RAML file (see loader.RAMLLoader)
  • InvalidRamlFileError – If error occurred trying to validate the RAML file (see validate)

Core

Note

The following documentation is meant for understanding the underlying ramlfications API. No need to interact directly with the modules, classes, & functions below.

parser

ramlfications.parser.parse_raml(loaded_raml, config)

Parse loaded RAML file into RAML/Python objects.

Parameters:loaded_raml (RAMLDict) – OrderedDict of loaded RAML file
Returns:raml.RootNode object.
ramlfications.parser.create_root(raml, config)

Creates a Root Node based off of the RAML’s root section.

Parameters:raml (RAMLDict) – loaded RAML file
Returns:raml.RootNode object with API root attributes set
ramlfications.parser.create_traits(raml_data, root)

Parse traits into Trait objects.

Parameters:
  • raml_data (dict) – Raw RAML data
  • root (RootNode) – Root Node
Returns:

list of raml.TraitNode objects

ramlfications.parser.create_resource_types(raml_data, root)

Parse resourceTypes into ResourceTypeNode objects.

Parameters:
  • raml_data (dict) – Raw RAML data
  • root (RootNode) – Root Node
Returns:

list of raml.ResourceTypeNode objects

ramlfications.parser.create_resources(node, resources, root, parent)

Recursively traverses the RAML file via DFS to find each resource endpoint.

Parameters:
  • node (dict) – Dictionary of node to traverse
  • resources (list) – List of collected ResourceNode s
  • root (RootNode) – The RootNode of the API
  • parent (ResourceNode) – Parent ResourceNode of current node
Returns:

List of raml.ResourceNode objects.

ramlfications.parser.create_node(name, raw_data, method, parent, root)

Create a Resource Node object.

Parameters:
  • name (str) – Name of resource node
  • raw_data (dict) – Raw RAML data associated with resource node
  • method (str) – HTTP method associated with resource node
  • parent (ResourceNode) – Parent node object of resource node, if any
  • api (RootNode) – API RootNode that the resource node is attached to
Returns:

raml.ResourceNode object

raml

class ramlfications.raml.RootNode

API Root Node

raw

Ordered dict of all raw data from the RAML file/string.

version

str of API version.

base_uri

str of API’s base URI.

base_uri_params

list of base URIParameter s for the base URI, or None.

uri_params

list of URIParameter s that can apply to all resources, or None.

protocols

list of str s of API-supported protocols. If not defined, is inferred by protocol from RootNode.base_uri.

title

str of API’s title.

docs

list of Documentation objects, or None.

schemas

list of dict s, or None.

media_type

str of default accepted request/response media type, or None.

resource_types

list of ResourceTypeNode objects, or None.

traits

list of TraitNode objects, or None.

security_schemas

list of SecurityScheme objects, or None.

resources

list of ResourceNode objects, or None.

raml_obj

The loader.RAMLDict object.

Note

TraitNode, ResourceTypeNode, and ResourceNode all inherit the following BaseNode attributes:

class ramlfications.raml.BaseNode
name

str name of Node

raw

dict of the raw data of the Node from the RAML file/string

root

Back reference to the Node’s API RootNode object.

headers

list of Node’s Header objects, or None

body

list of Node’s Body objects, or None

responses

list of Node’s Response objects, or None

uri_params

list of Node’s URIParameter objects, or None

base_uri_params

list of Node’s base URIParameter objects, or None

query_params

list of Node’s QueryParameter objects, or None

form_params

list of Node’s FormParameter objects, or None.

media_type

str of supported request MIME media type. Defaults to RootNode’s media_type.

description

str description of Node.

protocols

list of str s of supported protocols. Defaults to RootNode.protocols.

class ramlfications.raml.TraitNode

Object representing a RAML Trait.

In addition to the BaseNode-defined attributes, TraitNode also has:

usage

Usage of trait

class ramlfications.raml.ResourceTypeNode

Object representing a RAML Resource Type.

In addition to the BaseNode-defined attributes, ResourceTypeNode also has:

display_name

str of user-friendly name of resource type, defaults to BaseNode.name

type

str name of inherited ResourceTypeNode object, or None.

method

str of supported method.

Removes the ? if present (see optional).

usage

str usage of resource type, or None

optional

bool resource type attributes inherited if applied resource defines method (i.e. there is a ? in resource type method).

is_

list of assigned trait names (str), or None

traits

list of assigned TraitNode objects, or None

secured_by

list of str s or dict s of assigned security scheme, or None.

If str, then the name of the security scheme.

If dict, the key is the name of the scheme, the values are the parameters assigned (e.g. relevant OAuth 2 scopes).

security_schemes

list of assigned parameters.SecurityScheme objects, or None.

class ramlfications.raml.ResourceNode
parent

parent ResourceNode object if any, or None.

method

str HTTP method for resource, or None.

display_name

str of user-friendly name of resource. Defaults to name.

path

str of relative path of resource.

absolute_uri

str concatenation of absolute URI of resource: RootNode.base_uri + path.

is_

list of str s or dict s of resource-assigned traits, or None.

traits

list of assigned TraitNode objects, or None.

type

str of the name of the assigned resource type, or None.

resource_type

The assigned ResourceTypeNode object from ResourceNode.type, or None

secured_by

list of str s or dict s of resource-assigned security schemes, or None.

If a str, the name of the security scheme.

If a dict, the key is the name of the scheme, the values are the parameters assigned (e.g. relevant OAuth 2 scopes).

security_schemes

Parameters

Note

The URIParameter, QueryParameter, FormParameter, and Header objects all share the same attributes.

class ramlfications.parameters.URIParameter

URI parameter with properties defined by the RAML specification’s “Named Parameters” section, e.g.: /foo/{id} where id is the name of the URI parameter.

class ramlfications.parameters.QueryParameter

Query parameter with properties defined by the RAML specification’s “Named Parameters” section, e.g. /foo/bar?baz=123 where baz is the name of the query parameter.

class ramlfications.parameters.FormParameter

Form parameter with properties defined by the RAML specification’s “Named Parameters” section. Example:

curl -X POST https://api.com/foo/bar -d baz=123

where baz is the Form Parameter name.

class ramlfications.parameters.Header

Header with properties defined by the RAML spec’s ‘Named Parameters’ section, e.g.:

curl -H 'X-Some-Header: foobar' ...

where X-Some-Header is the Header name.

name

str of the name of parameter.

raw

dict of all raw data associated with the parameter from the RAML file/string.

description

str parameter description, or None.

display_name

str of a user-friendly name for display or documentation purposes.

If displayName is not specified in RAML data, defaults to name.

min_length

int of the parameter’s minimum number of characters, or None.

Note

Only applies when the parameter’s primative type is string.

max_length

int of the parameter’s maximum number of characters, or None.

Note

Only applies when the parameter’s primative type is string.

minimum

int of the parameter’s minimum value, or None.

Note

Only applies when the parameter’s primative type is integer or number.

maximum

int of the parmeter’s maximum value, or None.

Note

Only applies when the parameter’s primative type is integer or number.

example

Example value for parameter, or None.

Note

Attribute type of example will match that of type.

default

Default value for parameter, or None.

Note

Attribute type of default will match that of type.

repeat

bool if parameter can be repeated. Defaults to False.

pattern

str of a regular expression that parameter of type string must match, or None if not set.

enum

list of valid parameter values, or None.

Note

Only applies when parameter’s primative type is string.

type

str representation of the primative type of parameter. Defaults to string if not set.

required

bool if parameter is required.

Note

Defaults to True if URIParameter, else defaults to False.

class ramlfications.parameters.Body

Body of the request/response.

mime_type

str of the accepted MIME media types for the body of the request/response.

raw

dict of all raw data associated with the Body from the RAML file/string

schema

dict of body schema definition, or None if not set.

Note

Can not be set if mime_type is multipart/form-data or application/x-www-form-urlencoded

example

dict of example of schema, or None if not set.

Note

Can not be set if mime_type is multipart/form-data or application/x-www-form-urlencoded

form_params

list of FormParameter objects accepted in the request body.

Note

Must be set if mime_type is multipart/form-data or application/x-www-form-urlencoded. Can not be used when schema and/or example is defined.

class ramlfications.parameters.Response

Expected response parameters.

code

int of HTTP response code.

raw

dict of all raw data associated with the Response from the RAML file/string

description

str of the response description, or None.

headers

list of Header objects, or None.

body

list of Body objects, or None.

method

str of HTTP request method associated with response.

class ramlfications.parameters.Documentation

User documentation for the API.

title

str title of documentation

content

str content of documentation

class ramlfications.parameters.SecurityScheme

Security scheme definition.

name

str name of security scheme.

raw

dict of all raw data associated with the SecurityScheme from the RAML file/string

type

str of type of authentication

described_by

Header s, Response s, QueryParameter s, etc. that is needed/can be expected when using security scheme.

description

str description of security scheme.

settings

dict of security schema-specific information

class ramlfications.parameters.Content(data)

Returns documentable content from the RAML file (e.g. Documentation content, description) in either raw or parsed form.

Parameters:data (str) – The raw/marked up content data.
raw

Return raw Markdown/plain text written in the RAML file

html

Returns parsed Markdown into HTML

Loader

class ramlfications.loader.RAMLLoader

Extends YAML loader to load RAML files with !include tags.

load(raml)

Loads the desired RAML file and returns data.

Parameters:raml – Either a string/unicode path to RAML file, a file object, or string-representation of RAML.
Returns:Data from RAML file
Return type:dict

Validate

Functions are used when instantiating the classes from ramlfications.raml.

ramlfications.validate.root_version(inst, attr, value)

Require an API Version (e.g. api.foo.com/v1).

ramlfications.validate.root_base_uri(inst, attr, value)

Require a Base URI.

ramlfications.validate.root_base_uri_params(inst, attr, value)

Require that Base URI parameters have a default parameter set.

ramlfications.validate.root_uri_params(inst, attr, value)

Assert that where is no version parameter in the regular URI parameters

ramlfications.validate.root_protocols(inst, attr, value)

Only support HTTP/S plus what is defined in user-config

ramlfications.validate.root_title(inst, attr, value)

Require a title for the defined API.

ramlfications.validate.root_docs(inst, attr, value)

Assert that if there is documentation defined in the root of the RAML file, that it contains a title and content.

ramlfications.validate.root_media_type(inst, attr, value)

Only support media types based on config and regex

ramlfications.validate.assigned_traits(inst, attr, value)

Assert assigned traits are defined in the RAML Root and correctly represented in the RAML.

ramlfications.validate.assigned_res_type(inst, attr, value)

Assert only one (or none) assigned resource type is defined in the RAML Root and correctly represented in the RAML.

ramlfications.validate.header_type(inst, attr, value)

Supported header type

ramlfications.validate.body_mime_type(inst, attr, value)

Supported MIME media type for request/response

ramlfications.validate.body_schema(inst, attr, value)

Assert no schema is defined if body as a form-related MIME media type

ramlfications.validate.body_example(inst, attr, value)

Assert no example is defined if body as a form-related MIME media type

ramlfications.validate.body_form(inst, attr, value)

Assert formParameters are defined if body has a form-related MIME type.

ramlfications.validate.response_code(inst, attr, value)

Assert a valid response code.

ramlfications.validate.integer_number_type_parameter(inst, attr, value)

Assert correct parameter attributes for integer or number primative parameter types.

ramlfications.validate.string_type_parameter(inst, attr, value)

Assert correct parameter attributes for string primative parameter types.

ramlfications.validate.validate_mime_type(value)

Assert a valid MIME media type for request/response body.

Tree

ramlfications.tree.tree(load_obj, color, output, verbosity, validate, config)

Create a tree visualization of given RAML file.

Parameters:
  • load_obj (ramlfications.loader.RAMLDict) – Loaded RAML File
  • color (str) – light, dark or None (default) for the color output
  • output (str) – Path to output file, if given
  • verbosity (str) – Level of verbosity to print out
Returns:

ASCII Tree representation of API

Return type:

stdout to screen or given file name

Raises InvalidRamlFileError:
 

If error occured trying to validate the RAML file (see validate.py)