Restful API Modelling Language

1. 1.
2.
3.
4.
5.
6.
RAML
Restful API modeling language
RAML is a human- and machine-readable language for the definition of a RESTful application programming interface (API). RAML is designed to
improve the specification of such interfaces by providing a format that can serve as a useful contract between the API provider and the API
consumers, for example to facilitate providing user documentation and source code stubs for client and server implementations, thereby
streamlining and enhancing the definition and development of inter-operable applications that utilize RESTful APIs.
It's a way of describing practically-RESTful APIs in a way that's highly readable by both humans and computers. We say "practically RESTful"
because, in the real world, very few APIs today actually obey all constraints of REST. RAML isn't strict; for now, it focuses on cleanly describing
resources, methods, parameters, responses, media types, and other HTTP constructs that form the basis for modern APIs that obey many,
though perhaps not all, RESTful constraints.
RAML describes an API in a way that is
- The structure of the API should be manifest. Patterns are brought to the forefront; its data and interaction models are front andClear
center.
- An API spec is a contract: whatever is captured must correctly describe the behavior of the API.Correct
- Can a client be generated from the spec that's as faithful to the API as it is reasonable? Do the implementer know what they'rePrecise
required to deliver?
- RAML has strong support for capturing patterns. It encourages reuse, enables discovery and pattern-sharing, and aims forConsistent
merit-based emergence of best practices.
- Optimizes both creating and reading specs by impatient, smart humans.Readable & writable
- It is as close as possible to the mental model one has for the API, like what you'd type out in an email to a colleagueNatural & intuitive
or friend you were helping design or consume the API.
Why RAML?
Benefits of a single interface description
It removes duplication of effort and inconsistencies between multiple representations.
It can be collocated with source code to promote consistency between source code and documentation.
It can be used to generate static documentation, interactive documentation, client applications, server applications, and automated tests.
Benefits of using RAML vs. other products
Modularization of parts of the representation removes duplication and encourages API consistency through reuse.
The RAML API designer tool encourages a design-first approach instead of a document-after approach.
A RAML document contains the following information:
- Explains how to describe core aspects of the API, such as its name, title, location (or URI), and defaults. DescribesBasic Information
how to include supporting documentation for the API.
- Describes a means to model API data via a streamlined type system, which also encompasses JSON and XML Schema.Data Types
- Describes how to specify an API's resources and nested resources, as well as URI parameters in any URI template.Resources
- Describes how to specify the methods on the API’s resources, and their request headers, query parameters, and requestMethods
bodies.
- Describes the specification of API responses, including status codes, media types, response headers and response bodies.Responses
- Describes the optional mechanism for using RAML resource types and traits to characterize resources so asResource Types and Traits
to avoid unnecessary repetition in an API's definition and promote consistency and reuse.
- Describes the mechanisms available in RAML to specify an API’s security schemes.Security
- Describes a mechanism for extending a RAML specification by defining strongly-typed annotations and applying themAnnotations
throughout the specification.
- Describes how an API’s definition may be composed of externalized definition documents,Includes, Libraries, Overlays, and Extensions
how collections of such definitions can be packaged as libraries, how layers of metadata may be separated from and overlaid on top of a
RAML document, and how an API specification can be extended with additional functionality.
Structure of the RAML document
Mark-up Language
RAML API definitions are YAML-compliant documents that begin with a REQUIRED YAML-comment line that indicates the RAML version, as
follows:
#%RAML 0.8
It must be the first commented line of the RAML document.
The root of the document
The root section of the RAML document describes the basic information of an API, such as its title and version, as well as defining assets used
elsewhere in the RAML document such as types and traits. Following example shows an overview of RAML document:

2. 1.
2.
#%RAML 0.8
title: GitHub API
version: v3
baseUri: http://abc.com/A
mediaType: application/json
securitySchemes:
- oauth_2_0: !include securitySchemes/oauth_2_0.raml
types:
Gist: !include types/gist.raml
Gists: !include types/gists.raml
collection: !include typed/collection.raml
resourceTypes:
traits:
securedBy: [ oauth_2_0 ]
/search:
/code:
type: collection
get:
RAML document contains following properties:
Title - It specifies title of the API.
Version - optional property, specifies version of the API.
Description - optional property, describes the overall API in human friendly, extended manner.
User documentation - optional property, includes a variety of documents that serve as user guides and reference documentation for the
API. Such documents can clarify how the API works and provide technical and business context. The value of the documentation
property is an array of one or more documents. Each document is an object that must contain following two properties with non empty
string values.
title - Title of documentation section
content - Content of document section
Following example shows an API definition with user documentation:
#%RAML 0.8
title: ZEncoder API
baseUri: some url
documentation:
title: Home
content: |
Welcome to the Zencoder API Documentation. The Zencoder API
allows you to connect your application to our encoding service
and encode videos without going through the web interface. You
may also benefit from one of our
integration libraries for different languages.
Base URI and base URI parameters - optional property, specifies a URI as an identifier for the API as a whole, and may be used the
specify the URL at which the API is served, and which forms the base of the URLs of each of its resources.
Protocols - optional property, specifies the protocols that an API supports. If the protocols property is not explicitly included, the
protocol(s) specified at the baseUri property is used; if the protocols property is specified explicitly, it overrides any protocol specified in
the baseUri property. It must be a non-empty array of string, of values HTTP or HTTPS, and is case insensitive.
#%RAML 0.8
title: Salesforce Chatter REST API
version: v28.0
protocols: [ HTTP, HTTPS ]
baseUri: https://na1.salesforce.com/services/data/{version}/chatter
Default media type - optional property, specifies media types expected from API requests. Value of mediaType property must be a media
type string conforming to the media type specification in RFC 6838.

3. #%RAML 0.8
title: Salesforce Chatter REST API
version: v28.0
mediaType: application/json
baseUri: https://na1.salesforce.com/services/data/{version}/chatter
Default security - optional attribute , specifies security schemes to be applied to every method of every resource in the API. ForsecuredBy
e.g.
#%RAML 0.8
title: Salesforce Chatter REST API
version: v28.0
mediaType: application/json
baseUri: https://na1.salesforce.com/services/data/{version}/chatter
securedBy: [oauth_2_0, oauth_1_0]
securitySchemes:
oauth_2_0: !include oauth_2_0.yml
oauth_1_0: !include oauth_1_0.yml
Types
RAML introduces the notion of data types, which provides a concise and powerful way to describe the data in your API. The data can be in a URI
parameter, a query parameter, a request or response header, or a request or response body. Data types can be built in and defined explicitly. the
following example shows a user type with three properties: firstname, and lastname of type string, and age of type number.
#%RAML 0.8
title: Salesforce Chatter REST APItypes:
User:
type: object
properties:
firstname: string
lastname: string
age: number
/users/{id}:
get:
responses:
200:
application/json:
type: User
RAML types in a nutshell:
Types are similar to java classes but borrow additional features from JSON schema, XSD, and more expressive object oriented
languages.
Types are split into four families: scalars, objects, externals, and arrays
Object types - It is defined as below:

4. #%RAML 0.8
title: Salesforce Chatter REST APItypes:
User:
type: object
properties:
firstname: string
lastname: string
age: number
Array types - It is declared by using the array qualifier at the end of a type expression as below:
#%RAML 0.8
title: Salesforce Chatter REST APItypes:
types:
emails: object
type: Email[]
minItems: 1
uniqueItems: true
Scalar types - RAML provides a predefined set of Scalar types. You can "extend" these types and add further restrictions. These restrictions are
called "facets" and they exist both for scalar and object types.
Built-in scalar types:
string
number
integer
date
boolean file
enum, pattern can also be supported by RAML.
There are some additional attributes of types as below:
minLength - minimum number of characters in a property value
maxLength - maximum number of characters in a property value
minimum - specifies minimum value of parameter
maximum - maximum value of parameter
example - shows an example for a property value on UI of Restful API.
repeat - specifies parameter can be repeated. If it is set to true than parameter can be repeat. By default it has false value
required - make a parameter required in the API.
default - give default value for parameter
Using types in RAML
Types may be used in several positions:
Body ( JSON )
Body ( XML )
Body ( Web Form )
Headers
Query Parameters
URI Parameters
Serialization rules depend on both the type and the position in which it is used
When declaring a custom value type ( extending the "value" built-in type ) it will have "string" as its default serialization target.
When extending one of the built-in types, your type will inherit the serialization target
Resources and nested resources
Resources are identified by their relative URI, which MUST begin with a slash ("/"). Every property whose key begins with a slash, and is either at
the root of the API definition or is the child property of a resource property, is such a resource property.
A resource defined as a root-level property is called a top-level resource. Its property's key is the resource's URI relative to the baseUri (if any). A

5. resource defined as a child property of another resource is called a nested resource, and its property's key is its URI relative to its parent
resource's URI. Following example shows an API definition with one top-level resource, /gists, and one nested resource, /public.
#%RAML 0.8
title: Salesforce Chatter REST APItypes:
version: v3
baseUri: https//api.github.com
/gists:
displayName: Gists
/public:
displayName: Gists
The properties for resources are given in following table:
Property Description Value type
displayName An alternate, human-friendly name for the
resource.
StringType
description A longer, human-friendly description of the
resource.
Markdown string
get
patch
put
post
delete
options
head
The methods available on this resource. Object describing the method
is A list of the traits to apply to all methods
declared (implicitly or explicitly) for this
resource.
array, which can contain each of the
following elements:
* name of unparametrised trait
* a key-value pair with trait name as key and
a map of trait parameters as value
* inline trait declaration
type The resource type which this resource
inherits.
one of the following elements:
* name of unparametrized resource type
* a key-value pair with resource type name
as key and a map of its parameters as value
* inline resource type declaration
securedBy The security schemes that apply to all
methods declared (implicitly or explicitly) for
this resource.
array of security scheme names or a single
security scheme name
uriParameters Detailed information about any URI
parameters of this resource
object whose property names are the URI
parameter names and whose values
describe the values
Methods
These are operations that are performed on resource. The optional properties of a resource defineget, patch, put, post, delete, head, and options
its method. Resource can have all the resource properties described above. Apart from those properties it can have some additional properties as
below:
Property Description Value type
queryParameters Detailed information about any query
parameters needed by this method. Mutually
exclusive with queryString. It is a map in
which the key is the name of the header, and
the value is itself a map specifying the
header attributes, according to named
parameters.
Object whose property names are the query
parameter names and whose values
describe the values.

6. headers Detailed information about any request
headers needed by this method. It is a map
in which the key is the name of the header,
and the value is itself a map specifying the
header attributes, according to named
parameters.
Object whose property names are the
request header names and whose values
describe the values.
queryString Specifies the query string needed by this
method. Mutually exclusive with
queryParameters.
An object whose keys are the HTTP status
codes of the responses and whose values
describe the responses.
responses Information about the expected responses to
a request
An object whose keys are the HTTP status
codes of the responses and whose values
describe the responses.
body Some methods admit request bodies, which
are described by this property.
Object whose properties are either
1) media types and whose values are type
objects describing the request body for that
media type, or
2) a type object describing the request body
for the default media type specified in the
root mediaType property
Resource types and traits
There are many advantages of reusing patterns across multiple resources and methods. For example, after defining a collection-type resource's
characteristics, that definition can be applied to multiple resources. This use of patterns encourages consistency and reduces complexity for both
servers and clients.
A is a partial resource definition that, like a resource, can specify security schemes and methods and other properties. Resourcesresource type
that use a resource type inherit its properties. A resource type can also use, and thus inherit from, another resource type.
A is a partial method definition that, like a method, can provide method-level properties such as description, headers, query stringtrait
parameters, and responses. Methods that use one or more traits inherit those traits' properties. Resources and resource types can also use, and
thus inherit from, one or more traits, which then apply to all of their methods.
Declaration for resource types and traits
Resource types may be declared via the optional property at the root of the API definition. The value of this property is an objectresourceTypes
whose property names become names of resource types that can be referenced throughout the API, and whose property values are resource
type declarations.
Similarly, traits may be declared via the optional property at the root of the API definition. The value of this property is an object whosetraits
property names become names of traits that can be referenced throughout the API, and whose property values are trait declarations.
Resource type and traits can have following properties:
Property Description Value type
usage Instructions on how and when to use this
resource type in a RAML spec
Markdown string
uses You may import library locally here it
contents is accessible only inside of this trait
An array of libraries
parameters Optional declaration of the parameters that
the resource type employs.
An object whose property names are the
parameter names and whose property values
describe the parameter data types.
The following example illustrates the declaration of several resource types and traits.

7. #%RAML 0.8
title: Example API
version: v1
resourceTypes:
collection:
usage: This resourceType should be used for any collection of items
description: The collection of <<resourcePathName>>
get:
description: Get all <<resourcePathName>>, optionally filtered
post:
description: Create a new <<resourcePathName | !singularize>>
traits:
secured:
usage: Apply this to any method that needs to be secured
description: Some requests require authentication.
headers:
access_token:
description: Access Token
example: 5757gh76
required: true
The following example builds on the previous one, but the the resource types and traits are defined in external files that are included by using an
!include tag.
#%RAML 1.0
title: Example API
version: v1
resourceTypes:
collection: !include resourceTypes/collection.raml
member: !include resourceTypes/member.raml
traits:
secured: !include traits/secured.raml
rateLimited: !include traits/rate-limited.raml
Security
Most REST APIs have one or more mechanisms to secure data access, identify requests, and determine access level and data visibility. RAML
supports the following built-in security scheme types:
Type Description
OAuth 1.0 The API's authentication uses OAuth 1.0 as described in RFC5849
[RFC5849]
OAuth 2.0 The API's authentication uses OAuth 2.0 as described in RFC6749
[RFC6749]
Basic Authentication The API's authentication uses Basic Access Authentication as
described in RFC2617 [RFC2617]
Digest Authentication The API's authentication uses Digest Access Authentication as
described in RFC2617 [RFC2617]
Pass Through Headers or Query Parameters are passed through to the API based
on a defined mapping.
x-<other> The API's authentication uses an authentication method not listed
above.
Security scheme types
- Security schemes of this type have specific settings object.OAuth 1.0
Property Description Value type

8. requestTokenUri The URI of the Temporary Credential
Request endpoint as defined in RFC5849
Section 2.1
FixedUri
authorizationUri The URI of the Resource Owner
Authorization endpoint as defined in
RFC5849 Section 2.2
FixedUri
tokenCredentialsUri The URI of the Token Request endpoint as
defined in RFC5849 Section 2.3
FixedUri
Note: FixedUri type is a String, and should conform to the URI standard defined in RFC 3986. The following is an example for OAuth 1.0:
#%RAML 0.8
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
- oauth_1_0:
description:|
OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred.
type: OAuth 1.0
settings:
requestTokenUri: https://api.dropbox.com/1/oauth/request_token
authorizationUri: https://www.dropbox.com/1/oauth/authorize
tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token
OAuth 2.0 - Security schemes of this type have specific settings object:
Property Description Value type
accessTokenUri The URI of the Token Endpoint as defined in
RFC6749 [RFC6748] Section 3.2. Not
required forby implicit grant type.
FixedUri
authorizationUri The URI of the Authorization Endpoint as
defined in RFC6749 [RFC6748] Section 3.1.
Required forby authorization_code and
implicit grant types.
FixedUri
authorizationGrants A list of the Authorization grants supported
by the API as defined in RFC6749
[RFC6749] Sections 4.1, 4.2, 4.3 and 4.4,
can be any of:
* authorization_code
* password
* client_credentials
* implicit
* refresh_token.
StringType[]
scopes A list of scopes supported by the security
scheme as defined in RFC6749 [RFC6749]
Section 3.3
StringType[]
The following is an example for OAuth 2.0:

9. #%RAML 0.8
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
- oauth_2_0:
description: |
Dropbox supports OAuth 2.0 for authenticating all API requests.
type: OAuth 2.0
describedBy:
headers:
Authorization:
description: |
Used to send a valid OAuth 2 access token. Do not use
with the "access_token" query string parameter.
type: string
queryParameters:
access_token:
description: |
Used to send a valid OAuth 2 access token. Do not use together with
the "Authorization" header
type: string
responses:
401:
description: |
Bad or expired token. This can happen if the user or Dropbox
revoked or expired an access token. To fix, you should re-
authenticate the user.
403:
description: |
Bad OAuth request (wrong consumer key, bad nonce, expired
timestamp...). Unfortunately, re-authenticating the user won't help here.
settings:
authorizationUri: https://www.dropbox.com/1/oauth2/authorize
accessTokenUri: https://api.dropbox.com/1/oauth2/token
authorizationGrants: [ authorization_code, refresh_token ]
Basic - it does not require any further specification of settings in the API definition.

10. #%RAML 0.8
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
- basic:
description: |
This API supports Basic Authentication.
type: Basic Authentication
Digest - it does not require any further specification of settings in the API definition.
#%RAML 0.8
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
- digest:
description: |
This API supports Digest Authentication.
type: Digest Authentication
Pass through - Pass Through authentication does not have any specific settings defined and the implementation is known to RAML. For every
header or queryParameter defined in describedBy, the value is required and passed along with the request without modification. The following is
an example:
#%RAML 0.8
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
- passthrough:
description: |
This API supports PassThrough Authentication.
type: PassThrough
describedBy:
queryParameters:
query:
type: string
headers:
api_key:
type: string
Usage

11. The securedBy attribute of RAML document root may be used to apply security schemes to every method of API. This specifies that all methods
in the API (unless they have their own securedBy attribute) can be authenticated by any mentioned security scheme.
Applying a security scheme to a method overrides whichever security scheme has been applied to the API as whole. To indicate that the method
is protected using a specific security scheme, the method MUST be defined by using the securedBy attribute. The value assigned to the
securedBy attribute MUST be a list of any of the security schemas previously defined in thesecuritySchemes property of RAML document root.
#%RAML 0.8
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securedBy: [oauth_2_0]
securitySchemes:
- oauth_2_0: !include oauth_2_0.yml
- oauth_1_0: !include oauth_1_0.yml
/users:
get:
securedBy: [oauth_2_0, oauth_1_0]