RAML 1.0 scratchpad

RAML 1.0

Rename baseUri to baseUrl

The root property should be called baseUrl, because it really is the locator for the hosted API.

Also, it currently says:

The use of the baseUri field is OPTIONAL to allow describing APIs that have not yet been implemented. After the API is implemented (even a mock implementation) and can be accessed at a service endpoint, the API definition MUST contain a baseUri property.

It should always be optional.

The use of the baseUrl field is OPTIONAL.

Allow '/' in URI parameters

The spec says:

The baseUri property's value MUST conform to the URI specification [RFC2396] or a Level 1 Template URI as defined in RFC 6570 [RFC6570].

In order to be able to document more versatile APIs, we should also allow Level 2 templates, but only if the macro is the last piece in the URL

Example:

#%RAML 0.8
title: My Sample API
/files{+path}:
  uriParameters:
    path:
      description: The full path to the desired file
      type: string
      example: /my/file

Add displayName for methods

This will allow to give semantic names to methods, and simplify SDK or richer client generation.

Example:

#%RAML 0.8
title: My Sample API
/files:
  get:
    displayName: getFiles

Examples validation

In order to improve the quality of generated RAML specifications, we should add to the spec some wording like the following:

RAML processors MUST validate that examples for named parameters or responses are valid according to the schema, regular expressions or type.

Add support for JSONP

In order to support JSONP we should add a new jsonp property to methods. This property MUST be interpreted in the following way:

• If present in a method, this operation can be called using JSONP
• If the method is other than get, the URI can be called and the method property in the jsonp property must exist
• RAML processors MUST:
  • If the method is different from get, they MUST use the method property and send the method's name as a URI parameter
  • If the body property is defined, and the method defines a body, the body must be sent as a URI parameter (URL encoded)

Property Name	Description
callback	The name of the URI parameter used by the API to indicate the name of the Javascript function to call on responses.
method	The name of the URI parameter to submit the HTTP method (if different than GET)
body	The name of the URI parameter to submit the body of the request

#%RAML 0.8
title: My Sample API
baseUrl: http://myapi.io
/files:
  description: return a list of file metadata
  get:
    jsonp:
      callback: callback
  post:
    description: create a file
    jsonp:
      callback: callback
      method: APImethod
      body: body
    body:
      example: |
        {
          'name': 'my-file-name.txt',
          'created-date': 1409147946
        }

With this example, a request to retrieve file resources MUST be interpreted as a GET to http://myapi.io/files?callback=processResponse. With the same example, a file resource creation MUST be interpreted as a GET to /files

Add support for headers in JSONP

This is separate from the main JSONP discussion, because I have not seen a standard for this anywhere

We add a headers property to jsonp, if present:

• RAML processors must send any headers defined for the method as a JSON encoded object, where each key in the object is a header.

Property Name	Description
headers	The name of the URI parameter to submit any extra headers needed by the API

#%RAML 0.8
title: My Sample API
baseUrl: http://myapi.io
/files:
  description: return a list of file metadata
  get:
    jsonp:
      callback: callback
      headers: api-headers

Fix optional headers marker from { * } to {?}

The current value for patterns in header names should be {?}

Allow arbitrarily named Named Parameters

Extend the {?} syntax to all named parameters, except URI parameters.

Make a note that all markdown is GFM

RAML MUST be prescriptive and say which version of Markdown is valid in the documentation.

Remove prescription of JSON schema versions

RAML spec says that JSON schemas MUST be draft v 0.3. We should remove the restriction. Since all JSON schemas have the version embedded, we should allow RAML processors, list which versions of JSON schema they support.

Allow enum in Named Parameters be used for any parameter type

Remove the restriction that enums MUST only be used with type: string

Document resource type and trait composition

I originally documented it here:

https://github.com/mulesoft/api-designer/issues/203

In the case of traits, the rules are:

1. If the property is in the resource/method, then this will be the final value.
2. Traits are processed from left to right in the is: property, so the first trait to define the property gets to set the final value.

In the case of resource types, the rules are a bit more complex:

1. If the property is in the resource/method, then this will be the final value
2. Then resource types are mixed in: 1. The inheritance chain is walked up to the base type, its traits applied, and then the inheriting resource type's properties are mixed in with the parent resource type, where it is the inheriting type's property the ones who overrule the parent. 1. This is done recursively for all parent types, until a single representation for the entire chain has been reached. 1. This 'parent' resource type is then mixed in with the inheriting resource
3. Then the traits are mixed in with the resource as described above

The main guiding rule for both of these is: Whoever is closest to the resource gets to set the property first, in case of traits, it will be the first one in the list, in the case of resource types, it will be the closest in the inheritance chain.

Allow Dynamic, parameter-driven !includes

We should allow the following syntax for !includes in resource types and traits

#%RAML 0.8
title: My Sample API
resourceTypes:
  - collection:
      get:
      post:
        body:
          example: !include <<resourcePathName!singularize>>.json

Allow arrays and maps as resource types and traits parameters

In order to have more powerful traits and resource types, we should allow trait and resource types parameters be scalars, arrays, and maps, this will allow resource types like the following:

#%RAML 0.8
title: My Sample API
traits:
  - orderBy:
      description: Order by field
      type: string
      enum: <<filterValues>>
      required: false
/people:
  is: [orderBy: { filterValues: ['age', 'height'] } ]

Clarify named parameters authority

There is some ambiguity as to who is responsible for filling in the default values for named parameters.

For URI parameters, RAML clients MUST fill the default value into the URI before make requests to the API.
For Headers, Form Parameters, Query String Parameters, if the parameter is flagged as not `required` and having a `default` value, the API must act as if the API client has sent the parameter with the value being the value in the `default` property.

Clarify resource precedence when two URIs collide

When two resources have the same relative URI, and there are no URI parameters in the URIs, then the RAML should be invalid:

#%RAML 0.8
title: My Sample API
/users:
  me:
    get:
/users/me:
  post:

When there are URI parameters in the relative URIs, it is assumed that the API routing implementation can handle the ambiguity. In such cases, to resolve ambiguity, resources defined earlier in the RAML spec take precedence over resources declared later. In the following example, the definition of the route /users/me takes precedence over /users/{id}, and both routes are considered to be different resources.

#%RAML 0.8
title: My Sample API
/users/me:
  get:
/users:
  {id}:
    get:

New types property

New bodies property

Simplify resource specifications by making examples global at the same level as schemas.

Example:

#%RAML 0.8
title: My Sample API