Blog Post

Fragments in RAML-

• RAML stands for Restful API modeling language. It is used to write the specification of Restful APIs, which is understandable by both humans and machines.
• Fragments are the reusable logic that can be maintained through every API in API specification.
• There are two types of fragments:

1. Local fragments: These fragments are not published to exchange and are used in a single project.
2. Global fragments: These fragments are published to exchange and can be added to multiple projects as a dependency.

• The Fragments in the RAML1.0 are:
  • DataType.
  • SecuritySchemes
  • Traits.
  • Examples.
  • ResourceTypes.
  • Library.
  • Annotation Types
  • Extensions.
  • Overlays.
• In this blog, we’ll learn about some of the other fragments, which are resource types, Library, and extensions.

Resource Types-

• These reusable templates define the structure and behavior of resources in your API. They allow you to standardize common patterns for endpoints.
• It makes your API specification more concise and maintainable.
• They are defined using the keyword resourceTypes and referred to using the keyword type.
• Examples:

resourceTypes:

getResourceTypes:

get:

queryParameters:

mileage:

type: number

required: true

responses:

200:

body:

application/json:

example: |

<<getResponse>>

/cars:

type: {getResourceTypes: {getResponse: !include /Examples/carsGetResponse.json}}

/bikes:

type: {getResourceTypes: {getResponse: !include /Examples/bikeGetResponse.json}}

• • getResponse is a variable created, which can accept different values for different resources.
• To externalize the resourceTypes, we need to create a separate file of type resourceTypes and refer to the main file.

External Resource Types

resourceTypes:

get:

queryParameters:

temp:

type: number

required: true

responses:

200:

body:

application/json:

example: |

<<getResponse>>

Main RAML file

resourceTypes:

getRT: !include /Examples/getDestinationResponse.json

/places:

type: {getRT: {getResponse: !include /Examples/getDestinationResponse.json}

Library-

• It is a reusable component that allows you to define and organize common elements such as types, traits, resource types, annotations, security schemes, and schemas. It can be termed as a collection of fragments in a single file.
• It promotes reusability and modularity in your API specifications.
• It is referred to using the keyword uses in the main file and contents inside the library will be referred to by their specific keyword, for example, Trait is referred to using is keyword.
• Example:

#%RAML 1.0 Library

resourceTypes:

delRT:

delete:

headers:

AuthToken:

required: true

type: string

responses:

200:

body:

application/json:

example: {

“Message”:”Record has been deleted”

}

traits:

tokentrait:

queryParameters:

sptoken:

required: true

type: string

maxLength: 20

minLength: 9

example: “asdfghijkl”

Main RAML file:

uses:

lib: /library/library.raml

/users:

type: {lib.delRT}

is: [lib.tokentrait]

In the main RAML file, we need to create a placeholder i.e. lib in this case, and in the resource, we’ll use the same placeholder after the type for the resource type and is for the trait.

Extensions-

• Extensions are used to extend or override the behavioral aspects of the API using the keyword.
• It uses extended keywords to extend the properties of an API specification.
• It becomes helpful when there is a need to enhance an existing API without modifying the existing RAML.

Main RAML file:

#%RAML 1.0

title: rally-details

version: 1.0

/tracks:

get:

queryParameters:

trackid:

required: false

type: string

loc:

required: false

type: string

responses:

200:

body:

application/json:

example: !include /Examples/trackresponse.json

Extension file

#%RAML 1.0 Extension

extends:

/tracks:

post:

body:

application/json:

example:

{

“Loc”: “Rio”,

“trackid”: “101”,

“capacity”: “23000”

}

responses:

201:

body:

application/json:

example: {

“message”: “Track details have been updated”

}