RAML (RESTful API Modelling Language) 1.0 Advanced Example




RAML (RESTful API Modelling Language) 1.0 Advance 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.

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 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.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 :

extension is used to extend or override behavioral aspects of the API.As you may
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 :

A resource type, like a resource, can specify security schemes, methods, and other nodes. A resource that uses a resource type inherits its nodes. A resource type can also use, and thus inherit from, another resource type. Resource types and resources are related through an inheritance chain pattern. A resource type definition MUST NOT incorporate nested resources. A resource type definition cannot be used to generate nested resources when the definition is applied to a resource. A resource type definition does not apply to its own existing nested resources.


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.