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`) InvalidRootNodeError – API metadata is invalid according to RAML specification. InvalidResourceNodeError – API resource endpoint is invalid according to RAML specification. InvalidParameterError – Named parameter 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`) InvalidRootNodeError – API metadata is invalid according to RAML specification. InvalidResourceNodeError – API resource endpoint is invalid according to RAML specification. InvalidParameterError – Named parameter is invalid according to RAML specification. InvalidRAMLError – RAML file is invalid according to RAML specification.

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.
Raises:	`errors.InvalidRAMLError` when RAML file is invalid

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. The order of base_uri_params will follow the order defined in the RootNode.base_uri.

uri_params¶: list of URIParameter s that can apply to all resources, or None. The order of uri_params will follow the order defined in the RootNode.base_uri.

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. The order of uri_params will follow the order defined in the ResourceNode.absolute_uri.

base_uri_params¶: list of Node’s base URIParameter objects, or None. The order of base_uri_params will follow the order defined in the ResourceNode.absolute_uri.

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.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 (dict) – 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:	InvalidRootNodeError – API metadata is invalid according to RAML specification. InvalidResourceNodeError – API resource endpoint is invalid according to RAML specification. InvalidParameterError – Named parameter is invalid according to RAML specification.