RAML v1.0: Libraries

Libraries

Related issues:

• Issue 71

Libraries as described in the RAML spec

• used to combine any collection of Data Types, Resource Types, Traits, and Security Schemes
• primarily meant to be used with external documents, but also may be defined inline

Broad Implementation TODOs

• no need to parse objects defined in a library differently, e.g. Data Types, Resource Types, etc
• handle uses in the API root
• when applied, parse object references (see Proposed API Behavior for an example/further understanding)
• If a library refers to another library, if I understand the spec correctly, it should inherit/combine

Validation considerations

• External RAML files specifically for a library should have #%RAML 1.0 Library
• Valid properties for defining a library (all of which are optional):
  • types
  • schemas
  • resourceTypes
  • traits
  • securitySchemes
  • annotationTypes
  • (<annotationName>)
  • uses

Where to start

These are educated suggestions, and more meant for developers unfamiliar with the ramlfications package and are wanting to contribute.

• I don't think a whole Library object necessarily needs to be define (but open to arguments and thoughts)
• Related, I'm not sure the Root Node needs a property, uses.
• Each object defined in a library should be parsed according to its respective object, e.g. Data Types, Resource Types, etc
• Validation should occur when a uses property is hit (see validation considerations above)
• Not sure if ramlfications/loader.py should be affected in any way; perhaps if we want to do anything special with the file header of #%RAML 1.0 Library
• Every library property (see the second point in validation considerations) is optional, aka should handle a ? at the end of the property, e.g. types?

Proposed API Behavior

Input

Main RAML file, api.raml (snippet):

#%RAML 1.0
title: Files API
uses:
  files: !include libraries/files.raml
resourceTypes:
  file: !include files-resource.raml
/files:
  type: file

Referred files-resource.raml:

#%RAML 1.0 ResourceType
uses:
  files: !include libraries/files.raml
get:
  is: files.drm
  responses:
    200:
      body:
        application/json:
          type: files.file-type.File

Referred libraries/files.raml:

#%RAML 1.0 Library
# This file is located at libraries/files.raml
usage: |
  Use to define some basic file-related constructs.
uses:
  file-type: !include libraries/file-type.raml
traits:
  drm:
    headers:
      drm-key:
resourceTypes:
  file:
    get:
      is: drm
    put:
      is: drm

Referred libraries/file-type.raml

#%RAML 1.0 Library
# This file is located at libraries/file-type.raml
types:
  File:
    properties:
      name:
      length:
        type: integer

Expected Output

I would imagine the Python objects/behavior would look as follows:

>>> RAML_FILE = "api.raml"
>>> api = ramlfications.parse(RAML_FILE, version="1.0")
>>> api.title
'Files API'
>>> api.resources
[ResourceNode(method='get', path='/files')]
>>> files = api.resources[0]
>>> res_trait = files.traits[0]
>>> res_trait
TraitNode(name='drm')
>>>
>>> resp = files.responses[0]
>>> resp
Response(code='200')
>>> body = resp.body[0]
Body(mime_type='application/json')
>>> body.data_type
DataType(name='File')
>>> file_type = body.data_type
>>> file_type.family
'object'
>>> file_type.schema
# currently `body.schema` returns OrderedDicts
# but I could be convinced to do `jsonschema` objects for application/json
# and `lxml` objects for application/xml response bodies per issue #15
OrderedDict([('name', [OrderedDict([('type', 'string')])]), ('length', [OrderedDict([('type', 'integer')])]])
# I would also be open to something like this, not sure how other primative types would work:
OrderedDict([('name', [OrderedDict([('type', str)])]), ('length', [OrderedDict([('type', int)])]])