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:
  • Local fragments: These fragments are not published to exchange and are used in a single project.
  • 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 fragments, which are Data types, Security Schemes, and Traits.

Data Types

• RAML 1.0 introduces data types, which provide a concise and powerful way to describe the data in an API.
• It is defined using the keyword type.
• RAML 1.0 has support for the following data types:
  • String:
    • It is a type of datatype that has a set of characters that can include alphabets, numbers, and symbols inside double quotes.
    • We can provide a range for this datatype using the keyword:
      • minLength: It is used to specify the minimum length of a string datatype.
      • maxLength: It is used to specify the maximum length of a string datatype.
    • Example:

• Number:
  • It is a type of datatype that accepts only the numeric value.
  • It can be restricted to a specific range using the following keyword:
    • Minimum: It is used to specify the minimum number.
    • Maximum: It is used to specify the maximum number.
  • Example:

Type: number

• Boolean:
  • It is a type of datatype that has only two values i.e. true or false.
  • Example:

• Object:
  • It is a type of datatype i.e. in object format which can contain several attributes.
  • Example:

• Array:
  • It is a type of datatype i.e. in array format which can be a number array, string array, or collection of objects.
  • It uses the items keyword to define the type of array.
  • The size of the array can be restricted using the keywords:
    • minItems: It specifies the minimum number of elements in the array.
    • maxItems: It specifies the maximum number of elements in the array.
  • Example:

• Integer:
  • It is a type of datatype that accepts only integer values.
  • Examples:

• File:
  • It is a type of datatype that accepts only files.
  • It has a limit of 8.3 MB.
  • Example:

• Date-only:
  • It is a type of datatype that accepts only the date, with no implications about time or offset.
  • Example:

• Time-only:
  • It is a type of datatype that accepts only the time, with no implications about date or offset.
  • Example:

• DateTime-only:
  • It is a type of datatype that accepts only the datetime, with no implications about offset.
  • Example:

• Any:
  • It is a type of datatype that can accept any type of datatype.
  • Example:

• Nil:
  • It is a type of datatype that accepts only nil.
  • Example:

• To externalize the datatype, we need to create a separate file of type datatype and refer it in the main RAML file.

External Datatype file

#%RAML 1.0 DataType

Main RAML file:

            types:

              name: !include /DataTypes/nameDataType.raml

/students:

              get:

          queryParameters: 

            name:

              required: true

                responses:

                200:

                 body:

                  application/json:

                    example: !include Examples/getStudentsResponse.json

In the main RAML file, we’ll create a placeholder and we’ll make of that placeholder to refer to the datatype. In this case, we are making use of a name as a placeholder.

Security Schemes

• These are used to define the security mechanism that will be applied to all resources of the API or some specific resources of the API.
• It is created using the keyword securitySchemes and referred to using the keyword securedBy.
• It is described by using the keyword describedBy.
• Type keyword is used to specify the type of security applied.
• RAML1.0, supports the following policies at the specification level:
  • Basic Authentication.
  • OAuth1.0
  • OAuth2.0
  • Custom policy.
  • Digest Authentication.
  • Pass through.
• Example:

securitySchemes:

  basic:

    type: Basic Authentication

    describedBy: 

      headers:

        username:

          type: string

          minLength: 5

          maxLength: 15

          example: “username” 

        password:

          type: string

          minLength: 5

          maxLength: 15

          example: “password”

                        /students:

                           get:

                              securedBy: [basic] 

                                    responses:

                                       200:

                       body:

                              application/json:

                                            example: !include Examples/getStudentsResponse.json

• basic is the name for the security schemes.
• To externalize the security schemes, we need to create a separate file of type security scheme and refer to the main file.

External security schemes:

#%RAML 1.0 SecurityScheme

type: Basic Authentication

describedBy: 

  headers:

    username:

      type: string

      minLength: 5

      maxLength: 15

      example: “username” 

    password:

      type: string

      minLength: 5

      maxLength: 15

      example: “password”

Main RAML file:

securitySchemes:

  basicAuth: !include /Security Schemes/basicAuthsecurityScheme.raml

/students:

  get:

    securedBy: [basicAuth] 

    responses:

      200:

        body:

          application/json:

            example: !include Examples/getStudentsResponse.json

In the main RAML file, we need to create a placeholder i.e. basicAuth in this case, and in the resource, we’ll use the same placeholder after the securedBy keyword to apply the policy on the resource.

Traits

• Traits are the set of behaviors that can be applied to different parts of API.
• It is created using the keyword traits and referred to using the keyword is.
• Example:

traits:

  qpTrait:

    queryParameters:

      dept:

        type: string

        required: true

        example: “CSE”

/students:

  get:

    is: [qpTrait]

    responses:

      200:

        body:

          application/json:

            example: !include Examples/getStudentsResponse.json

• qpTrait is the name of the trait, using which it will be referred to in the resource.
• To externalize the Trait, we have to create a separate file type of Trait and that needed to be referred in the main file.

External Trait file

#%RAML 1.0 Trait

responses:

  500:

    body:

      application/body:

        example: ../Examples/500_errorResponse.json

  400:

    body:

      application/json:

        example: ../Examples/400_errorResponse.json

  404:

    body:

      application/json:

        example: ../Examples/404_errorResponse.json

  405:

    body:

      application/json:

        example: ../Examples/405_errorResponse.json

Main RAML file

traits:

  error: !include /Traits/errorTrait.raml

/students:

  get:

    is: [error]

    responses:

      200:

        body:

          application/json:

            example: !include Examples/getStudentsResponse.json

The above external trait is an error trait that has all the error responses. In the main RAML file, we have to create a placeholder that will be used to refer to the resource.