RAML (RESTful API Modelling Language) 1.0 Advanced Example
Here is the example of advance raml 1.0 where some sections of raml are divided into segments like :
employeeDetails.raml
library
documentation
examples
schemas
extension
overlays
In our example :
1. employeeDetails is the main raml.
2. first line is raml version,after this title comes than api version.
3. protocols tag is used to specify on which protocol api works.
4. documentaion tag is used for api documentation.We have seperated api documentation in a separate file that is documentation.raml.
5. types tag is used for including schemas.json schemas are present in a separate schema folder.
6. uses tag is used to include libraries in main raml. Library is present in a separate folder library as library.raml.
7. we can define security schemes in our raml by securitySchemes tag in raml.
8. query parameters can be used queryParameters tag.In this required attribute is used to specify whether it is mandatory parameter or not.if mandatory then set it to true otherwise false.
2. first line is raml version,after this title comes than api version.
3. protocols tag is used to specify on which protocol api works.
4. documentaion tag is used for api documentation.We have seperated api documentation in a separate file that is documentation.raml.
5. types tag is used for including schemas.json schemas are present in a separate schema folder.
6. uses tag is used to include libraries in main raml. Library is present in a separate folder library as library.raml.
7. we can define security schemes in our raml by securitySchemes tag in raml.
8. query parameters can be used queryParameters tag.In this required attribute is used to specify whether it is mandatory parameter or not.if mandatory then set it to true otherwise false.
9. is tag is used to include library content in raml. In our example traits and errors are used as content.
10. All examples are extracted in a separate folder examples.
11. In raml we can also specify nested resources in raml by { } under resources.
employeeDetails.raml :
#%RAML 1.0
title: dbcrud
version: v1
mediaType:
- application/json
protocols: [HTTP,HTTPS]
documentation:
- title: User Details
content: !include documentation/documentation.raml
types:
insertReqSchema: !include schemas/insertReqSchema.json
updateReqSchema: !include schemas/updateReqSchema.json
annotationTypes:
department: string
uses:
files: Library/library.raml
securitySchemes:
basicAuth:
description: It is used for authenticating uses by username & password
type: Basic Authentication
describedBy:
headers:
client_id: string
client_secret: string
/employee:
get:
(department): IT
is: [files.client-id-required,files.client-secret-required,files.errors]
queryParameters:
id:
description: for fetching employee on the basis of id
required: false
minimum: 1
maximum: 100
type: integer
example:
2
responses:
200:
body:
application/json:
example: !include examples/searchRes
post:
is: [files.client-id-required,files.client-secret-required,files.errors]
description: for posting employees data
body:
application/json:
example: !include examples/insertReq
description: Request body for inserting the data
type: !include schemas/insertReqSchema.json
responses:
201:
body:
application/json:
example: !include /examples/insertRes
put:
securedBy:
- basicAuth
is: [files.client-id-required,files.client-secret-required,files.errors]
description: for updating employees data
body:
application/json:
example: !include examples/updateReq
description: Request body for updating the data
type: !include schemas/updateReqSchema.json
responses:
204:
body:
application/json:
example: !include /examples/updateRes
delete:
securedBy:
- basicAuth
is: [files.client-id-required,files.client-secret-required,files.errors]
description: for deleting employees data
responses:
202:
body:
application/json:
example: !include /examples/deleteRes
/{id} :
get:
is: [files.client-id-required,files.client-secret-required, files.errors]
description: for getting data of specific employee
displayName : /employee/id
responses:
200:
body:
application/json:
example: !include examples/searchIdRes
delete:
is: [files.client-id-required,files.client-secret-required, files.errors]
description: for deleting data of specific employee
displayName : /employee/id
responses:
200:
body:
application/json:
example: !include examples/deleteIdRes
Libraries in RAML :
RAML libraries may be used to modularize any number and combination of data types,
security schemes, resource types, traits, and annotations.
Although usually defined in an external file, which is then referenced as an include, a library may also be defined inline. A library contained in an external file can reference other libraries as well. Unlike a regular include or typed fragment, a library contained in an external file must declare the top-level element names that are being defined.
in main raml uses and is tags are used to include libraries.
Let's write our traits and errors section as a library file: library.raml :
RAML libraries may be used to modularize any number and combination of data types,
security schemes, resource types, traits, and annotations.
Although usually defined in an external file, which is then referenced as an include, a library may also be defined inline. A library contained in an external file can reference other libraries as well. Unlike a regular include or typed fragment, a library contained in an external file must declare the top-level element names that are being defined.
in main raml uses and is tags are used to include libraries.
Let's write our traits and errors section as a library file: library.raml :
#%RAML 1.0 Library
usage: collection of traits
traits:
client-id-required:
headers:
client_id:
type: string
minLength: 4
maxLength: 12
required: true
description: client id & client secret is required for authentication purpose.
client-secret-required:
headers:
client_secret:
type: string
minLength: 4
maxLength: 12
required: true
description: client id & client secret is required for authentication purpose.
errors:
responses:
401:
body:
application/json:
example: {
"error" : "unauthorized access"
}
404:
body:
application/json:
example: {
"error" : "URL not found"
}
405:
body:
application/json:
example: {
"error" : "Method not allowed"
}
502:
body:
application/json:
example: {
"error" : "Bad API Gateway"
}
Documentation in RAML :
for api documentation in detail we use documentation.raml that means we can separate the detailed documentation
in a separate file. This documentation is included in our main raml by include tag.
Documentation in RAML :
for api documentation in detail we use documentation.raml that means we can separate the detailed documentation
in a separate file. This documentation is included in our main raml by include tag.
documentation.raml :
#%RAML 1.0 DocumentationItem
title: User details
content: The API performs CRUD operations about user details
Overlays in RAML :
An overlay is used to extend non-behavioral aspects of an API, such as descriptions,
usage directions, and user documentation items.If we have an api working for different countries and we need to do
documentation in multiple languages then overlays can be used.
overlays.raml :
#%RAML 1.0 Overlay
title: API documentation in multiple languages
extends: documentation.raml
documentation:
- title: Introducción
content: El acceso automatizado a los libros
- title: Licencias
content: Por favor respeta los derechos de autor de los libros
Extensions in RAML :
infer from the name, extensions are used to extend an API by adding new behaviors
and/or modifying existing behaviors of an API.Here we are fetching the employees list by name which
is done by adding /{name} as nested resource in our /employee resource.
extension.raml :
#%RAML 1.0 Extension
title: Person list on the basis of name
extends: employeeDetails.raml
/employee:
/{name}:
get:
description: for getting data of specific employee
responses:
200:
body:
application/json:
example: !include examples/searchRes
Schemas in RAML :
for including schemas in our main raml we can use type tag as shown above
in employeeDetails.raml all schemas are placed in a separate folder.
insertReqSchema.json :
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"lastname": {
"type": "string"
},
"firstname": {
"type": "string"
},
"address": {
"type": "string"
},
"city": {
"type": "string"
}
},
"required": [
"id",
"lastname",
"firstname",
"address",
"city"
]
}
updateReqSchema.json :
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"lastname": {
"type": "string"
},
"firstname": {
"type": "string"
},
"address": {
"type": "string"
},
"city": {
"type": "string"
}
},
"required": [
"id",
"lastname",
"firstname",
"address",
"city"
]
}
Resource Types in RAML :
Traits in RAML :
A trait, like a method, can provide method-level nodes such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit nodes of those traits. A resource and resource type can also use, and thus inherit from, one or more traits, which then apply to all methods of the resource and resource type. Traits are related to methods through a mixing pattern.
