What's New in RAML 1.0
RAML 1.0 is all about empowering developers with even more extensibility, code reuse options, and flexibility.
This includes exciting new features such as libraries, overlays, improved examples, improved security schemas, annotations, and data-typing. Here's just a little bit more on each of these features, and how they make designing, building, testing, documenting, and sharing your API even easier. Of course, you can always read the full spec to learn more.
Libraries
Libraries provide the ability to bring in pre-defined sets of data-types, resourceTypes, traits, security schemas, and reusable assets - all in a namespaced environment.
#%RAML 1.0
title: A CRUD API for Users and Groups
mediaType: application/json
uses:
Common: libraries/types/common.raml
User: libraries/types/user.raml
Group: libraries/types/group.raml
CRUD: libraries/resourceTypes/crud.raml
/users:
description: All the users
type:
CRUD.collection:
typename: User.full
typename-new: User.new
Overlays
Overlays let you add an additional layer to your RAML file and include new information such as descriptions, annotations, and examples - letting you extend your main RAML file for different internal and external API use cases.
Improved Security Schemas
Substantial improvements have been made to enhance security schema support in RAML 1.0, including improved support for OAuth (1&2) and a brand new "Pass Through" schema
#%RAML 1.0
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 ]
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
customHeader:
description:|
A custom header
Annotations
Annotations, or a way to extend your RAML specification to support specific third-party vendor needs without breaking or changing your specification have now been added. Using annotations and overlays you can now meet specialized use-case needs all without having to worry about breaking backwards compatibility with other services.
#%RAML 1.0
title: Testing annotations
mediaType: application/json
annotationTypes:
experimental: null | string
feedbackRequested: null | string
assertion: string
testHarness: string
badge: string
clearanceLevel:
properties:
level:
enum: [ low, medium, high ]
required: true
signature:
pattern: "\\d{3}-\\w{12}"
required: true
/groups:
(experimental):
(feedbackRequested):
/users:
(testHarness): usersTest
(badge): tested.gif
(clearanceLevel):
level: high
signature: 230-ghtwvfrs1itr
get:
(experimental):
(feedbackRequested):
responses:
200:
(assertion): Condition 1
Data Types
Perhaps the crown jewel in RAML 1.0, data types serve as a way of replacing daunting schemas and provide even more information for consumers and code generators to ensure that they understand and meet your API data type needs.
Data Types can be used in place of schemas and examples, letting you define one Data Type that can then be converted into an XML or JSON Schema on the fly - letting you simply define your data model, and letting RAML take care of the REST.
#%RAML 1.0
title: A CRUD API for Users and Groups
mediaType: application/json
types:
###############
# Common:
###############
Email:
pattern: "^\\w+(\\.\\w+)?@company.com"
StaticGroupNums:
description: Predefined user groups
enum: [ 12, 26, 30, 31, 32 ]
DynamicGroupNum:
description: Dynamically-defined user groups
pattern: "D\\-\\d+"
RecordId:
usage: An id of any record in the system
type: number
Record-base:
usage: Pattern for any record in the system
properties:
id:
type: RecordId
required: true
created:
type: date
required: true
###############
# User:
###############
User-base:
usage: The base type for user records
properties:
firstname:
required: true
lastname:
required: true
User-new:
usage: Data for creating a new user
type: User-base
properties:
HRAuth:
description: Authorization received from HR
required: true
User-update:
usage: Changeable properties of an existing user
properties:
firstname:
lastname:
User:
usage: A user in the system
type: [ User-base, Record-base ]
properties:
emails: Email[]
###############
# Group:
###############
Group-base:
usage: The base type for group records
properties:
name:
required: true
Group-new:
usage: Data for creating a new group
type: Group-base
properties:
ITAuth:
description: Authorization received from IT
required: true
Group-update:
usage: Changeable properties of an existing group
properties:
name:
Group:
usage: A group in the system
type: [ Group-base, Record-base ]
properties:
groupnum:
type: StaticGroupNums | DynamicGroupNum
required: true
resourceTypes:
###############
# Collection:
###############
collection:
get:
responses:
200:
body:
properties:
total:
type: number
required: true
members: <>[]
post:
body:
type: <>
responses:
201:
headers:
Location:
required: true
body:
type: <>
###############
# Member:
###############
member:
get:
responses:
200:
body:
type: <>
patch:
body:
type: <>
responses:
200:
body:
type: <>
delete:
responses:
204:
deleteOnlyMember:
delete:
responses:
204:
###############
# API:
###############
/users:
description: All the users
type:
collection:
typename: User
typename-new: User-new
/{userId}:
description: A specific user
uriParameters:
userId: RecordId
type:
member:
typename: User
typename-update: User-update
/groups:
description: The groups to which this user belongs
type:
collection:
typename: Group
typename-new: RecordId
/{groupId}:
type: deleteOnlyMember
delete:
description: Remove this user from this group
/groups:
description: All the groups
type:
collection:
typename: Group
typename-new: Group-new
/{groupId}:
description: A specific group
uriParameters:
groupId: RecordId
type:
member:
typename: Group
typename-update: Group-update
/users:
description: The users belonging to this group
type:
collection:
typename: User
typename-new: User-new
/{userId}:
type: deleteOnlyMember
delete:
description: Remove this user from this group
To learn more about What's New - check out this blog post