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 withparser.parse_raml()
to return araml.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 withvalidate.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 currentnode
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 baseURIParameter
s for the base URI, orNone
.
-
uri_params
¶ list
ofURIParameter
s that can apply to all resources, orNone
.
-
protocols
¶ list
ofstr
s of API-supported protocols. If not defined, is inferred by protocol fromRootNode.base_uri
.
-
title
¶ str
of API’s title.
-
docs
¶ list
ofDocumentation
objects, orNone
.
-
schemas
¶ list
ofdict
s, orNone
.
-
media_type
¶ str
of default accepted request/response media type, orNone
.
-
resource_types
¶ list
ofResourceTypeNode
objects, orNone
.
-
security_schemas
¶ list
ofSecurityScheme
objects, orNone
.
-
resources
¶ list
ofResourceNode
objects, orNone
.
-
raml_obj
¶ The
loader.RAMLDict
object.
-
Note
TraitNode
, ResourceTypeNode
, and
ResourceNode
all inherit the following BaseNode
attributes:
-
class
ramlfications.raml.
BaseNode
¶ -
name
¶ str
name ofNode
-
raw
¶ dict
of the raw data of theNode
from the RAML file/string
-
uri_params
¶ list
ofNode
’sURIParameter
objects, orNone
-
base_uri_params
¶ list
ofNode
’s baseURIParameter
objects, orNone
-
query_params
¶ list
ofNode
’sQueryParameter
objects, orNone
-
form_params
¶ list
ofNode
’sFormParameter
objects, orNone
.
-
description
¶ str
description ofNode
.
-
protocols
¶ list
ofstr
s of supported protocols. Defaults toRootNode.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 toBaseNode.name
-
type
¶ str
name of inheritedResourceTypeNode
object, orNone
.
-
usage
¶ str
usage of resource type, orNone
-
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
), orNone
-
secured_by
¶ list
ofstr
s ordict
s of assigned security scheme, orNone
.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 assignedparameters.SecurityScheme
objects, orNone
.
-
-
class
ramlfications.raml.
ResourceNode
¶ -
parent
¶ parent
ResourceNode
object if any, orNone
.
-
method
¶ str
HTTP method for resource, orNone
.
-
display_name
¶ str
of user-friendly name of resource. Defaults toname
.
-
path
¶ str
of relative path of resource.
-
absolute_uri
¶ str
concatenation of absolute URI of resource:RootNode.base_uri
+path
.
-
is_
¶ list
ofstr
s ordict
s of resource-assigned traits, orNone
.
-
type
¶ str
of the name of the assigned resource type, orNone
.
-
resource_type
¶ The assigned
ResourceTypeNode
object fromResourceNode.type
, orNone
-
secured_by
¶ list
ofstr
s ordict
s of resource-assigned security schemes, orNone
.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}
whereid
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
wherebaz
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, orNone
.
-
display_name
¶ str
of a user-friendly name for display or documentation purposes.If
displayName
is not specified in RAML data, defaults toname
.
-
min_length
¶ int
of the parameter’s minimum number of characters, orNone
.Note
Only applies when the parameter’s primative
type
isstring
.
-
max_length
¶ int
of the parameter’s maximum number of characters, orNone
.Note
Only applies when the parameter’s primative
type
isstring
.
-
minimum
¶ int
of the parameter’s minimum value, orNone
.Note
Only applies when the parameter’s primative
type
isinteger
ornumber
.
-
maximum
¶ int
of the parmeter’s maximum value, orNone
.Note
Only applies when the parameter’s primative
type
isinteger
ornumber
.
-
example
¶ Example value for parameter, or
None
.Note
Attribute type of
example
will match that oftype
.
-
default
¶ Default value for parameter, or
None
.Note
Attribute type of
default
will match that oftype
.
-
repeat
¶ bool
if parameter can be repeated. Defaults toFalse
.
-
pattern
¶ str
of a regular expression that parameter of typestring
must match, orNone
if not set.
-
enum
¶ list
of valid parameter values, orNone
.Note
Only applies when parameter’s primative
type
isstring
.
-
type
¶ str
representation of the primative type of parameter. Defaults tostring
if not set.
-
required
¶ bool
if parameter is required.Note
Defaults to
True
ifURIParameter
, else defaults toFalse
.
-
-
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 theBody
from the RAML file/string
-
schema
¶ dict
of body schema definition, orNone
if not set.Note
Can not be set if
mime_type
ismultipart/form-data
orapplication/x-www-form-urlencoded
-
example
¶ dict
of example of schema, orNone
if not set.Note
Can not be set if
mime_type
ismultipart/form-data
orapplication/x-www-form-urlencoded
-
form_params
¶ list
ofFormParameter
objects accepted in the request body.Note
Must be set if
mime_type
ismultipart/form-data
orapplication/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 theResponse
from the RAML file/string
-
description
¶ str
of the response description, orNone
.
-
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 theSecurityScheme
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 atitle
andcontent
.
-
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
ornumber
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
orNone
(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
)