Raml

What is RAML Root of RAML Datatype Defining Datatypes

The Root Node of RAML

RAML API specification begins at the root section of the document. The root section describes the basic information about an API, such as its title, version, baseUri, etc. The root section also defines assets used elsewhere in the RAML document, such as types and traits.

The first line of a RAML file consists of a comment that specifies the RAML version.


#%RAML 1.0
title: Accounts API

The following table lists the possible nodes at the root of RAML document. The nodes defines with '?' are optional.

Name Description
title A short text to name the API.
description? Description about the API.
version? Version of the API.
baseUri? The base URI of all the resources. Often used as the base of the URL of each resource containing the location of the API.
baseUriParameters? A parameter used in the baseUri.
protocols? The protocols supported by the API.
mediaType? The default media types to use for request and response bodies.
documentation? Documentation for the entire API.
types? Declarations of (data) types for use within the API.
traits? Declarations of traits for use within the API.
resourceTypes? Declarations of resource types for use within the API.
annotationTypes? Declarations of annotation types for use by annotations.
()? Annotations to be applied to this API. An annotation is a map having a key that begins with "(" and ends with ")" where the text enclosed in parentheses is the annotation name, and the value is an instance of that annotation.
securitySchemes? Declarations of security schemes for use within the API.
securedBy? The security schemes that apply to every resource and method in the API.
uses? Imported external libraries for use within the API.
/? The resources of the API, identified as relative URIs that begin with a slash (/). A resource node is one that begins with the slash and is either at the root of the API definition or a child of a resource node. For example, /users and /{UserId}.

As of RAML 1.0, schemas node is deprecated so use Types instead.

Documentation:

This is an optional node which is used for documentation purpose. Use this node to explain the API specification for the end user. The value of the documentation contains title and content. Each of these are a map and must include two key-value pair.

Name Description
title Title of the document. Its value MUST be a non-empty string.
content Content of the document. Its value MUST be a non-empty string. 

#%RAML 1.0
title: Programmerspub API
baseUri: https://app.programmerspub.com/api
documentation:
    - title: API Information
      content: |
        This is the documentation content. Use this to categorize and document the API specification.
        Use the | (pipe symbol) to start from next line.
    - title: Legal
      content: !include folderName/legal.raml
    - title: API RateLimit Policy
      content: Describe the rate limit policy of this API.

Base URI:

This is an optional node to specify URI (Uniform Resource Identifier) for the API or to specify the service endpoint URL of each of its resources. The base URI may take version as a parameter. Version is a reserved base URI parameter.

URI Parameter Value
version The value of the root-level version node 
#%RAML 1.0
title: Programmerspub API
version: 1
baseUri: https://{appName}.programmerspub.com/{version}/api
baseUriParameters:
  appName:
    description: The name of the application

Protocols:

This is an optional node which specifies the protocol(s) supported by the API. If the protocols node is specified, it overrides the protocol specified in the baseUri. If the node is not specified, it takes the protocol specified in the baseUri. 

Example of an API endpoint that accepts both HTTP and HTTPS requests.

#%RAML 1.0
title: Programmerspub API
version:v2
protocols: [HTTP, HTTPS]
baseUri: https://app.programmerspub.com/{version}/api

Media Types:

This is an optional node to specify the default media type for the enitre API with the request and response having a body. If a different mediaType was specified in the request or response body, it overrides the mediaType specified in the root section.

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

In the following example, the resource /articles returns a Tutorial[] body represented as JSON or XML. The resource /newArticles overrides the defualt media type and returns only JSON formatted response.

#%RAML 1.0
title: Programmerspub API
version: 1
baseUri: https://app.programmerspub.com/{version}/api
mediaType: [ application/json, application/xml ]
types:
   Tutorial
   How-to
/articles:
  get:
    responses:
      200:
        body: Tutorial[]
/newArticles:
  get:
    body:
      application/json:
       type: How-to

SecuredBy:

This is an optional node to specify the security schemas for each method of every resource in the API. The value of the node is an array of security scheme names. 

#%RAML 1.0
title: Programmerspub API
version: 1
baseUri: https://app.programmerspub.com/{version}/api
securedBy: [ oauth_2_0, oauth_1_0 ]
securitySchemes:
  oauth_2_0: !include securitySchemes/oauth_2_0.raml
Previous Next