RAML (RESTful API Modeling Language) Specification

The securedBy node sets the default security schemes that apply to every method of every resource in the API. The value must be an array of security scheme names defined in the securitySchemes node.

#%RAML 1.0
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securedBy: [ oauth_2_0, oauth_1_0 ]
securitySchemes:
  oauth_2_0: !include securitySchemes/oauth_2_0.raml
  oauth_1_0: !include securitySchemes/oauth_1_0.raml

The mediaType node sets the default media type for all request and response bodies. It can be a single string or a sequence of strings. Explicitly defining a mediaType within a specific body (request or response) overrides this default.

#%RAML 1.0
title: New API
mediaType: [ application/json, application/xml ]

/people:
  get:
    responses:
      200:
        body: Person[]

/messages:
  post:
    body:
      application/json:
        type: Another

You can create specialized RAML files called 'Typed Fragments' by starting the file with a specific fragment identifier. This allows you to modularize specific parts of your API like data types, traits, or resource types.

Common Fragment Identifiers:

• DocumentationItem
• DataType
• NamedExample
• ResourceType
• Trait
• AnnotationTypeDeclaration
• Library
• Overlay
• Extension
• SecurityScheme

Example of a ResourceType fragment:

#%RAML 1.0 ResourceType

description: A collection resource
get:
  description: Retrieve all items

#%RAML 1.0 ResourceType

description: A collection resource
usage: Use this to describe a resource that lists items
get:
  description: Retrieve all items
post:
  description: Add an item
  responses:
    201:
      headers:
        Location:

In RAML 1.0, you can make a property optional using the ? suffix in the property name.

Important: If you explicitly specify the required facet in a type declaration, any ? in the property name is treated as part of the literal name rather than an optionality indicator. To make a property with a trailing question mark optional, you must use either required: false or a double question mark ?? suffix.

Examples:

• Standard optional property: age?: number
• Explicitly optional: age: { type: number, required: false }
• Optional property with a literal question mark in the name: preference??:

types:
  Person:
    properties:
      name: string
      age?: number

  profile:
    properties:
      preference??:

Annotations cannot be directly applied to scalar-valued nodes (like baseUri or version) using standard syntax. To annotate a scalar node, you must use a map-valued syntax where the actual value is assigned to a key named value. This allows you to attach annotations as additional key-value pairs to that map.

Supported scalar-valued nodes include: displayName, description, type, schema, default, example, usage, required, content, strict, minLength, maxLength, uniqueItems, minItems, maxItems, discriminator, minProperties, maxProperties, discriminatorValue, pattern, format, minimum, maximum, multipleOf, requestTokenUri, authorizationUri, tokenCredentialsUri, accessTokenUri, title, version, baseUri, mediaType, extends.

baseUri:
  value: http://www.example.com/api
  (redirectable): true

A trait is a partial method definition that provides method-level properties such as description, headers, queryParameters, and responses. Methods inherit these using the is property.

Traits are declared at the root level under the traits key. A method can use one or more traits, or a resource can apply a list of traits to all its methods using the is property.

Note: Traits can be applied to all methods of a resource by using the is property at the resource level.

#%RAML 0.8
title: Example API
version: v1
traits:
  - secured:
      usage: Apply this to any method that needs to be secured
      description: Some requests require authentication.
      queryParameters:
        access_token:
          description: Access Token
          type: string
          example: ACCESS_TOKEN
          required: true

RAML provides two ways to modify an existing API definition (the 'master' document):

1. Overlays: Used to add or override non-behavioral metadata (e.g., title, description, documentation, examples, annotations). Overlays cannot change the functional behavior (resources, methods, parameters, etc.) of the API.
2. Extensions: Used to broaden or modify the actual behavior of the API (e.g., adding new resources, methods, or changing baseUri).

Both require a root-level extends node pointing to the master document.

Overlay Syntax: #%RAML 1.0 Overlay
Extension Syntax: #%RAML 1.0 Extension

#%RAML 1.0 Overlay
usage: Spanish localization
extends: librarybooks.raml
documentation:
  - title: Introducción
    content: El acceso automatizado a los libros
/books:
  description: La colección de libros de la biblioteca

You can create sub-types that inherit properties from a parent type by setting the type facet of the sub-type to the name of the parent type.

Restrictions on overriding parent properties:

1. A required property in a parent type cannot be changed to optional in a sub-type.
2. A property's type in a sub-type can only be changed to a narrower type (a specialization of the parent type).

#%RAML 1.0
title: My API With Types
types:
  Person:
    type: object
    properties:
      name:
        type: string
  Employee:
    type: Person
    properties:
      id:
        type: string