Sincerest apologies if i'm mistaking / overlooking something in the spec here whilst my eyes glare over after days of cross-reading specs, slide presentations, "REST"ful articles trying to come up with a sensible prototype - but i kinda bumped into this:

# ...
securitySchemes:
 - oauth_2_0:
    description: |
        The IWK Weather API supports OAuth 2.0 for authenticating all API requests.
    type: OAuth 2.0
    settings:
      authorizationUri: https://example.com/futile_constraint/but_why?authorizationGrant=code#is-not-the-case-here
      accessTokenUri: https://api.meteoplus.net/1/oauth2/authentication
      authorizationGrants: [ credentials ]
# ...

In this example the api only implements Oauth 2.0 section 4.4, which in my understanding is "1-legged" authentication, not requiring any authorization endpoint redirect and such. Same with section 4.3

At the same time, RAML Section 08_security.md puts a constraint on the existence of securitySchemes.settings.authorizationUri.

This is unexpected behaviour or a logical contradiction - again, pls forgive me if i overlooked s.th. blantantly here.

NB: I acknowledge the fact that Oauth2.0 is a particularly hard example to get right in this trait-like declaration - definition of 'right' or at least 'better' in my possibly opinionated view means: one ideally never ends up writing s.th. like

this is a required parameter, when we are in the xy flow context. Don't use when parameter z1 is set

at least this "itches" somehow - apart from that: so far it's been just pure ❤️ for the spec and it's ecosystem! Thanks so much for pulling this together.

Clarify that resource types cannot generate nested resources nor do they apply to nested resources.

My API endpoint can take a starts_at and ends_at parameter. Either both should be omitted, or both should be provided. How do I document this using the RAML spec?

The spec defines resource level traits, stating they should be applied to all methods within the resource:

A trait may also be applied to a resource by using the is key, which is equivalent to applying the trait to all methods for that resource, whether declared explicitly in the resource definition or inherited from a resource type.

But the spec is silent on whether these traits should also be inherited by nested resources.

The spec says that "the description property MAY be formatted using Markdown".

We've noticed (with the instagram RAML) that a description might have markdown embedded in it by mistake:

description: |
        … the user_has_liked key which ...

which results in italics via Markdown.

We should discuss having a single format for documentation, either markdown, plaintext or some other format.

With Magento and Jira we have faced the following problem:

URIs in security schemas are defined as relative to domain.
For example, in Megento we have:

baseUri: "{protocol}://{domain}/api/rest"
securitySchemes:
  - oauth_1_0:
    type: OAuth 1.0
    settings: 
      requestTokenUri: "{protocol}://{domain}/oauth/initiate"
      authorizationUri: "{protocol}://{domain}/oauth/oauth_authorize"
      tokenCredentialsUri: "{protocol}://{domain}/oauth/token"

http://www.magentocommerce.com/api/rest/authentication/oauth_authentication.html

We noticed notebooks not to support such definition and refered to the RAML spec. The spec does not make it clear how to describe security schemas with variable URIs.

In order to support both legacy and new clients I'd like to change the response schema based on a "format" queryParameter or HEADER.

Is this possible in RAML?

From what I see in the docs schemas are either bound to a media type or a response code but for my use case it would be two different payload formats which are both application/json and both 200 just formulated differently based on the requested format.

Hello.
I'm trying to resolve ambiguity of resource definition.
Assume I have the resource /a/b. The Raml spec says that I should use nested resource if /a is a resource itself. If not I can use /a/b. Both ways are correct. But the spec does not prohibit (or I missed it) api like this:

/a:
  /b: !include b1.raml
/a/b: !include b2.raml

IMHO spec should explicitly say "Any described resource MUST have an unique absolute URI". I've found out that api-disigner marks my sample as error. But java raml parser does not.

The example resource type ins the Resource Types and Traits / Optional Properties section is invalid.

The resource type has to optional methods, a post and a delete, both of which attempt to define a parameters in the body of a request (createAuthority and deleteAuthority respectively). But the example defines these properties directly in the body property, which is invalid.

Per the the spec:

A method's body is defined in the body property as a hashmap, in which the key MUST be a valid media type.

Presumably the authors meant these parameters to be form parameters, as they are defined within a body. If that is the case, then they should have been defined under the formParameters property, which in turn should be under one of the two web form media types as keys in the body property.

E.g.

#%RAML 0.8
title: Example of Optional Properties
resourceTypes:
  - auditableResource
      post?:
        body:
          application/x-www-form-urlencoded:
            formParameters:
              createAuthority:
                description: |
                  If the resource has a post method defined, expect a createAuthority
                  property in its body
      delete?:
        body:
          multipart/form-data:
            formParameters:
              deleteAuthority:
                description: |
                  If the resource has a delete method defined, expect a deleteAuthority
                  property in its body

The spec does say that baseUriParameters override root baseUriParameters, but it does not say that a method's should override the ones defined at a resource level.

method's (trumps) ==> resource's (trumps) ==> root's

What about add an option to define dates as ISO 8601?

This format is still very human-readable, and it is better supported by all the languages, including native support in JavaScript:

date1 = new Date();
iso8601Str = date1.toJSON();  // "2013-10-31T12:35:36.864Z"
date2 = new Date(iso8601Str);
date1.toString() === date2.toString()  // true

I agree with XKCD about this subject:

Original XKCD 1179.

[]'s
Racum

The type and is properties allow for inline definitions of resource types and traits. The spec is not clear on how these should be formatted. Specifically, do these definitions needs to be named (i.e. a map with a single property that is the type/trait name, with the value of the property being the definition) or not (i.e. the map is the definition, without being wrapped in a map with the name).

The spec provides not examples of resource types or traits defined inline within a type or is property, so its unclear.

It would be great if it would be possible to use two traits for one api end point. And to show that the end point can answer with either one of the two ways.

traits:
  - secured_key:
      responses:
        401:
          body:
  - secured_token:
      responses:
        401:
          body:
/keys:
  is: [ secured_key, secured_token ]

I wondering if a grammar could be defined for the RAML spec. If one were defined, any language that supports parsing of that grammar would then be able to create an Abstract Syntax Tree, thus allowing for more parsers in more languages more quickly. In particular, I was looking at using some of the Go tools ( go tool yacc raml_grammar.txt ) in order to do some Go code generation.

Thanks

This issue stems from http://stackoverflow.com/questions/24297204/how-do-you-reference-example-request-body-in-raml/25057093.

Schema's are first class elements within rAML but Example's are not, this doesn't allow defining examples anywhere but in the Resource so Schema and Example code can never live side by side unless both inlined. As shown in the answer of the Stack Overflow post YAML anchors can be used to reference the Example but it still must be defined within the Resource. This doesn't allow clean separation of the API structure and data definition within the rAML document and is somewhat inconsistent IMHO. Allowing all data definitions, Schemas and Example, to be defined side by side outside of a Resource or even within a different file would allow cleaner and more consistent readability.

Making Example's first class elements and allowing them to be referenced similar to how Schema are is one possible solution. Some new container element to allow specifying anchors as mentioned in the SO post by Amr Mostafa is another.

It would be nice to have a script (or app) that will generate nice-looking documentation (in HTML) from RAML.

I am wondering if the authors of the spec intended to use two different wildcards for request headers versus response headers or whether this was an oversight.

The spec defined {*} as a wildcard for request headers and {?} for response headers. This seems unnecessary and confusing.

Currently, it is not possible to programatically override the default OAuth 2.0 access token parameter name. For example, LinkedIn uses oauth2_access_token while typically the standard is just access_token. Having a way to set the property in the security schema settings would be help immensely.

We should be able to override all parameter names that may change, the code, client id, client secret, etc.

Suppose you have a service, in which customers can define their own fields for data. Then there's the API which allows said customers to access and filter said data. Now, there are common parts in the API for all customers: the endpoints, pagination params, sorting params, etc. Only the filtering bits change according to customer specific choices.

Example:

A: /people?sort=surname&field_not_defined_for_B=some_filtering_value

vs.

B: /people?sort=surname&field_not_defined_for_A=some_other_filtering_value

How would this kind of API best described? Should there be some sort of catch-all queryParameters entry/reserved word/attribute to denote, that "this end point accepts possible customer-specific filter key-value pairs"?

This API representation question is an issue only when trying to present a general view of the API. Obviously, in specific customer cases the API description could be complemented with some sort of automatically generated, customer specific include file. The presence of said include tag might also suffice for such a clue for the reader:

# main_spec.raml
/people:
  get:
    queryParameters:
      query:
        description: A search string
        type: string
      !include customer_people_params.raml

This definition would mean, that /people endpoint accepts a parameter "query" and is supposed to accept whatever is defined for a specific customer, even if specified file is not available.

What do you think?

On another note, is this GitHub issue tracker even right place to discuss this kind of things?

baseUri's should not end in slashes (unless they are meant to be there specifically), because they result in double slashes at the beginning of resource URIs.

I've seen conversations on this topic but they are all a bit old. In those conversations, the tools to generate docs (HTML output) from RAML comments have been promised as being "in the works." Is anything available to do this now?

Since json is a subset of YAML, it would be nice if we could specify the json schemas in-structure with the RAML. These two examples would become possible:

/{songId}:
  get:
    body:
      application/json:
        schema: {
          "$schema": "http://json-schema.org/schema",
          "type": "object",
          "description": "The canonical song representation",
          "properties": {
            "title":  { "type": "string" },
            "artist": { "type": "string" }
          },
          "required": [ "title", "artist" ]
        }

(Notice the lack of the | in the schema object)

Or, more interestingly,

/{songId}:
  get:
    body:
      application/json:
        schema:
          $schema: "http://json-schema.org/schema"
          type: "object"
          description: "The canonical song representation"
          properties:
            title:
              type: "string"
            artist:
              type: "string"
          required:
            - "title"
            - "artist"

This would allow the json-schema to "fit in" better with the RAML schema, in addition to making available the use of things like !include for subsections of a json-schema. Just an idea!

The spec is silent on whether traits can be used within resource types, either at the resource type level or the method level within a resource type definition. None of the examples show this usage, but there doesn't seem to be any reason why it would not be valid and it would certainly be useful when composing resource types.

At the moment the Spec is the main source of documentation. In order to allow for Implementations like ours to be well documented, a section is needed which detail those parts of the spec which are NOT implemented.

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, Level 2 templates should also be allowed, 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

One of the issues we've had with choosing RAML and writing tools around it is that the routes aren't namespaced:

#%RAML 0.8
title: World Music API
baseUri: http://example.api.com/{version}
version: v1
traits:
  - paged: ...
  - secured: !include http://raml-example.com/secured.yml
/songs: ...

we can rewrite this as:

config: ...
config: ...
/route: ...
/route: ...

In addition to being sloppy taxonomically, this makes parsing very peculiar. You have to look at every key to see if it starts with a slash in order to determine the content type?

Would it not be better to just:

config: ...
config: ...
routes:
  /route: ...
  /route: ...

or

resources:
  /route: ...

In this case, enumerating routes just becomes a matter of listing the keys inside of routes:{...}

This also would open up different use cases in the future, like

routes: !include routes/*

I've been working on a basic API with an included JSON schema file but I can't get the !include to work as expected.
I get an error in API Designer that says:
error: cannot fetch http://localhost:8080/schema/name.json, check that server is up and that CORS is enabled
I have attempted to enable CORS on the node.js server at port:8080 and even attempted to disable CORS blocking in Chrome. What am I missing? Is this a missing feature in API Designer?
Can someone provide a working example using !include ?

The spec states that:

The value of the type attribute MUST be either a) ..., or b) one and only one resource type definition map.

and

The value of the is attribute MUST be an array of any number of elements, each of which MUST be a) ..., or b) one or more trait definition maps.

So far, so good. If we come across a map in a type or is attributes, then they will be a type definition and a trait definitions.

But the spec also says:

To pass parameter values to resource types and traits, use a map when declaring the resource type or trait to be used.

Now we can't easily tell whether a map in a type or is attribute is a resource type/trait name with parameters or a definition.

We can try to guess. types/traits names with arguments will consist of an object with a single property with a value that is a map, and the single property must exist in the top-level resouceTypes/traits attributes. But maybe there is a typo, in which case we'll end up parsing the definition as a resource type or trait, maybe generating an error, maybe not.

When parsing a RAML document, the value of a schema property is ambiguous. It could be interpreted as an actual schema or a schema reference. Even if you assume the value is a schema and not a reference, there is no certain way to determine what type of schema the author meant (e.g. JSON schema, XML schema).

One could attempt to scan the value trying to match it against a known type of schema, but this is error prone. If the schema is invalid, you may fail to detect its intended type, and then you may wrongly assume it to be a reference.

When the property is meant to store a schema, then an associated mediate type should be provided to clearly identify the type of schema we are dealing with. And a schema reference also needs to be clearly distinguishable. You could do this by introducing a new data type (e.g. !schema_ref), by using different data types as the value of the property (e.g. a string for a schema reference, and an object with properties for the schema and its media type), or something along these lines.

The spec does not specify how to handle resource types and traits with properties that clash with the properties of the resources or methods they are applied against.

E.g. what should happen when a trait that defined a query parameter of "foo" is applied to a method that already defined a query parameter of the same name, or what should happen when a resource type is applied to a resource with a method that already defined a response with the same status code with the same media type but a different body schema.

A parser can either choose to raise an exception or merge the properties, with one stomping on the other. If the choice the later, the spec should specify which properties take precedence, trait over method, resource type over resource, or vice versa (actually, also trait over resource type, as a type can contain a trait).

It would be expected that parameter values are always uri encoded to avoid breaking things when making requests, but the current undefined behaviour in the spec allows RAML to be written that is expected to violate this.

There are 8 links at http://raml.org/spec.html that point to localhost instead of the correct heading in the documentation.

For example:

according to the <a href="http://localhost:5000/#named-parameters">Named Parameters section</a>

These same links work just fine from GitHub however.

So, say we're generating an API client automatically based on a RAML spec. I watched the video and noticed that your client seems to auto-generate a method named after the URI parameters in resource URIs. (such as music.songs.songId and notFB.userId).

So that's cool, but it seems like this strategy must have ambiguities. Take, for example:

/songs:
    /{songId}: ...
    /id-{songId}: ...

How do you distinguish these in the API? or how about this:

/songs:
    /{songId}:
        /{metadataKey}: ...
    /{songId}-{metadataKey}: ...

I can imagine the client library just punting and not allowing a convenient syntax for such ambiguous cases, and requiring the user to enter the full path, but it seems like it's begging for a solution in RAML. Like, some concept of unique "operation names" that must be specified, which would allow the API-implementor to easily look up all the parameters required to execute a given operation.

I'm trying to create a client for RAML-specified APIs in Clojure, and this is a big question mark in the design right now. Maybe I'm missing some other idea; it would be great to hear what you guys did for the javascript library! :)

Sorry if this isn't exactly a bug, but I can't figure out how else to talk to anyone else involved in RAML :)

http://www.restdoc.org/

This is another API documentation specification. It seems there would be some overlap of goals and ideas?

Is it worth investigating to see if they cover anything not covered here?

Is it worth discussing possible collaboration and teamwork?

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

I'd like to parameterize a trait so that instead of:

orderBy:
          description: Order by field
          type: string
          enum: [lastUpdated, name, createdAt]
          required: false

I have

orderBy:
          description: Order by field
          type: string
          enum: << values >>
          required: false

I would like raml to allow for global example definitions. Otherwise I am forced to fill out the very hierarchy I avoid when using global schema definitions and resourceTypes.
For example. Given the resourceType:

collection:
  type: base
  post:
    body:
      schema: post-<<resourcePathName | !singularize>> # e.g. post-sale

I can now reference schema automatically for all collection resources in my hierarchy. However, when I want to provide an example for a method on a collection I am forced to fill out the hierarchy. For example:

  /sales:
    type: collection
    post:
      body:
        example: |
          Unknown macro: { "machineId" }
    get:
      responses:
        201:
          body:
            example: |
              Unknown macro: { "count" }

which could have been avoided with a mere reference to a global example at the resourceType definition. For example:

collection:
  type: base
  post:
    body:
      schema: post-<<resourcePathName | !singularize>> # e.g. post-sale
      example: post-<<resourcePathName | !singularize>>-example

The spec says that any property in an RT or trait, to which a "?" is appended, becomes optional, and its value is only composed if the target resource has the property.

What then of properties which are scalars and have a null value. In the following example, what should be the output?

#%RAML 0.8
title: Some API
resourceTypes:
  - resourceType1:
      description?: Some Description
/res:
  type: resourceType1
  description:

In my opinion, optional flags should apply only to structures, if it does, the RAML above is incorrect, and processors should emit an error.

Hi there,

When parsing a raml file, whose body response references a previously defined schema (sample below)

  /{id}: 
    uriParameters: 
      id: 
        displayName: id 
        description: | 
          the unique id of the incident report 
        type: integer 
    get: 
      description: | 
        Retrieves the incident report with the specified id. 
      responses: 
        200: 
          description: | 
            OK. 
          body: 
            application/json: 
              schema: report 
              example: | 
                { 
                  "id": 20934, 
                  "title": "Lynn's Leaking Water Heater", 
                  "customer": 123, 
                  "createdon": "2014-01-20 23:15:03 EDT" 
                } 

the returned js literal, does not contain the schema name anymore, instead it replaces the name by the json schema value, as if it was an inline schema from the beginning.

Is there a way to change this behavior and have the parser return the schema name?

Cheers,
George

The same way that strings have their own applicable properties (maxLength) and integer (maximum) which are useful for validations, Parameters of type "file" could include properties such as maxFilesize, minFilesize, and fileType.
Of course different implementations SHOULD/MUST react accordingly.

The Basic Information / URI Parameters section incorrectly discusses a top level uriParameters property. This should be a discussion of the top-level baseUriParameters property. To my knowledge there is no top-level uriParamters property.

The discussion of the property, as well as the example RAML, are incorrect.

Currently, one can only add a single example json. It would be a nice enhancement to allow multiple examples like this:

      body:
        application/json:
          example: !include example1.json
          example: !include example2.json

The spec provides a way to define named schemas, but in "Schemas and Responses", it doesn't explain how to reference a schema defined in the root. It only shows how to do define the schema inline, or via an include.

If I define schemas at the root, like:

schemas:
  User:  schema/user.json
  Users: schema/users.json
  Org:   schema/org.json
  Orgs:  schema/orgs.json

Then I'd expect to be able to use that schema in a response definition like:

/users/{userId}:
  get:
    body:
      application/json:
        schema: User

It shows the schemas property as a map, instead of an array of maps:

#%RAML 0.8
title: Example API
version: v1
mediaType: application/json
schemas:
  users: !include schemas/users.json
  user: !include schemas/user.json

Adding an new "requires" validation parameter could be useful when validation queries. I would like to suggest the syntax requires: path for specifying that a parameter requires another for use. For example:

queryParameters:
  lat:
    type: string
    requires: lng
  lng:
    type: string
    requires: lat

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.

Hi,

I was wondering what is the correct way to represent nested form parameters. In an api im using i have to send the location information this way:

location:
        geo:
            lng:
            lat:
    country:
    state:
    city:
    town:

Thanks, i love raml!

According to https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#named-parameters-with-multiple-types you can have multiple types with validations, but you can't have mixed types with repeat. You can only specify repeat on each of the values in the array, but that would require every type to be of the same. Imaginably, this makes validation a little tricky. It's a similar issue with required, since you can specify multiple types but one can be not required and pass validation.

The spec uses minimum and maximum for parameter validation, but then also uses minLength and maxLength. Shouldn't it standardise on a single naming scheme - max/max and minLength/maxLength or minimum/maximum and minimumLength/`maximumLength? I'd be in favour of less typing and more consistency.

The spec states:

A method MUST be one of the HTTP methods defined in the HTTP version 1.1 specification [RFC2616] and its extension, RFC5789 [RFC5789].

That means any of the following methods are allowed: options get head post put delete trace connect patch.

The CONNECT and TRACE methods are of no use whatsoever when defining a REST API. The CONNECT method does not define an action on an end-point and the TRACE method merely echos back a request body. The spec should specify that these methods are not allowed since it makes no sense to support them.

Similarly, the OPTIONS method has no well defined semantics, although a case could be made for its use. (E.g. see http://zacstewart.com/2012/04/14/http-options-method.html). But even these proposals are of no use when defining an API. Rather, they are about API discovery. So I suggest that OPTIONS be disallowed as well.