DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Understanding Resource Types and Traits With RAML

Read this article in order to learn more about how to use resourceType and Traits with RAML.

Jitendra Bafna user avatar by
Jitendra Bafna
CORE ·
Jun. 13, 18 · Tutorial
Like (16)
Save
Tweet
Share
120.57K Views

Join the DZone community and get the full member experience.

Join For Free

1.0 What Is RAML?

RAML is a Rest API Modeling Language and it is based on YAML for describing your API's. It is basically used to describe your API, which can be easily readable by humans and computers. It basically focuses on describing your API resources, methods, parameters, media type etc.

2.0 What Is ResourceTypes?

ResourceTypes is like resource in that it can specify the descriptions, methods, and its parameters. Resource that uses resourceTypes can inherit its nodes. ResourceTypes can use and inherit from other resourceTypes.

ResourceType is basically a template that is used to define the descriptions, methods, and parameters that can be used by multiple resources without writing the duplicate code or repeating code.

Let's consider an example. Resource songs want to implement two methods like GET and POST. Each HTTP method will have responseTypes, description, usage, etc.

Now, we have other requirements that resource artists want to implement two methods like GET and POST. So, we will make use of resourceTypes to implement the GET and POST methods and that can be used by both resources songs and artist and it can even be used by other resources in the future.

2.1 Declaring ResourceTypes With HTTP Methods GET and POST

resourceTypes: 
  collection:
    usage: This API is used by <<resourcePathName>>
    description: API is used ti retrieve and create <<resourcePathName>>
    get:
    post:

2.2 Defining the HTTP POST and GET Method ResponseType and Description

resourceTypes: 
  collection:
    usage: This API is used by <<resourcePathName>>
    description: API is used ti retrieve and create <<resourcePathNam>>
    get:
      description: This API is used to retrieve all details about <<resourcePathName>>
      responses: 
        200:
          body: 
            application/json:
              example: |
                <<examplereference1>>
    post:
      description: This API is used to create <<resourcePathName>>
      body: 
        application/json:
          example: |
            <<exampleReference2>>
      responses: 
        201:
          body: 
            application/json:
              example: |
                {"message":"<<resourcePathName>> created"}

Reserved Parameters

  • <<resourcePath>> represents the entire URI.
  • <<resourcePathName>> repesents the part of URI following the righmost forward slash (/).

2.3 Calling ResourceTypes From Resources.

/songs:
  type: 
    collection:
        exampleReference1: |
          {"Songs":[
          {"SongID":1,"SongName":"London Dreams"},
          {"SongID":2,"SongName":"German Whip"}
          ]}
        exampleReference2: |
          {"SongID":1,"SongName":"London Dreams","Singer":"David"}
/artists:
  type:
    collection:
        exampleReference1: |
          {"Artists":[
          {"ArtistID":1,"ArtistName":"David"},
          {"ArtistID":2,"ArtistName":"John"}
          ]}
        exampleReference2: |
          {"ArtistID":1,"ArtistName":"John","D.O.B":"27 July 1978"}

Here we can see the songs and artists resources are calling the resourceTypes without repeating any code.

2.4 Complete RAML

#%RAML 1.0
baseUri: https://mocksvc.mulesoft.com/mocks/f1bfb7c0-370c-43ea-b6c2-5ec56bbf7513 # 
title: Songs

resourceTypes: 
  collection:
    usage: This API is used by <<resourcePathName>>
    description: API is used ti retrieve and create <<resourcePathName>>
    get:
      description: This API is used to retrieve all details about <<resourcePathName>>
      responses: 
        200:
          body: 
            application/json:
              example: |
                <<exampleReference1>>
    post:
      description: This API is used to create <<resourcePathName>>
      body: 
        application/json:
          example: |
            <<exampleReference2>>
      responses: 
        201:
          body: 
            application/json:
              example: |
                {"message":"<<resourcePathName>> created"}

/songs:
  type: 
    collection:
        exampleReference1: |
          {"Songs":[
          {"SongID":1,"SongName":"London Dreams"},
          {"SongID":2,"SongName":"German Whip"}
          ]}
        exampleReference2: |
          {"SongID":1,"SongName":"London Dreams","Singer":"David"}
/artists:
  type:
    collection:
        exampleReference1: |
          {"Artists":[
          {"ArtistID":1,"ArtistName":"David"},
          {"ArtistID":2,"ArtistName":"John"}
          ]}
        exampleReference2: |
          {"ArtistID":1,"ArtistName":"John","D.O.B":"27 July 1978"}

2.5 Testing API

The first step before testing API is to enable Mocking service using the Toggle Button.

Image title

For testing the API, we will going to use POST method of songs resource and click on "Try it."

Image title

After clicking on Try it, click on the Send button and it will make POST call to songs API. You can see response 201-Created with proper response message.

Image title

3.0 What Is Traits?

Traits is like function and is used to define common attributes for HTTP method (GET, PUT, POST, PATCH, DELETE, etc) such as whether or not they are filterable, searchable, or pageable.

3.1 Declaring Traits

Traits can be declared in the same RAML file or you can create different files for creating the traits.

Here, you will see how we can implement a response in traits and how it can be called by multiple resources and resourceTypes.

traits: 
    responseMessage:
      responses: 
        200:
          body: 
            application/json:
              example: |
                {"message":"Data Created"}

3.2 Calling Traits From Resources

Traits can be called by resources using the "is" keyword.

#%RAML 1.0
baseUri: https://mocksvc.mulesoft.com/mocks/f1bfb7c0-370c-43ea-b6c2-5ec56bbf7513 # 
title: Songs

traits: 
    responseMessage:
      responses: 
        200:
          body: 
            application/json:
              example: |
                {"message":"Data Created"}

/albums:
  post:
    body: 
      application/json:
        example: |
          {"AlbumID":1,"AlbumName":"German Whip"}
    is: [responseMessage]

3.3 Calling Traits From ResourceTypes

Traits can be called from ResourceTypes using the "is" keyword only.

traits: 
    responseMessage:
      responses: 
        200:
          body: 
            application/json:
              example: |
                {"message":"<<resourcePathName>> Created"}
resourceTypes: 
  collection:
    usage: This API is used by <<resourcePathName>>
    description: API is used ti retrieve and create <<resourcePathName>>
    get:
      description: This API is used to retrieve all details about <<resourcePathName>>
      responses: 
        200:
          body: 
            application/json:
              example: |
                <<exampleReference1>>
    post:
      description: This API is used to create <<resourcePathName>>
      body: 
        application/json:
          example: |
            <<exampleReference2>>
      is: [responseMessage]

3.4 Complete RAML(Showing How to Call Traits From Resources and ResourceTypes) 

#%RAML 1.0
baseUri: https://mocksvc.mulesoft.com/mocks/f1bfb7c0-370c-43ea-b6c2-5ec56bbf7513 # 
title: Songs

traits: 
    responseMessage:
      responses: 
        200:
          body: 
            application/json:
              example: |
                {"message":"<<resourcePathName>> Created"}
resourceTypes: 
  collection:
    usage: This API is used by <<resourcePathName>>
    description: API is used ti retrieve and create <<resourcePathName>>
    get:
      description: This API is used to retrieve all details about <<resourcePathName>>
      responses: 
        200:
          body: 
            application/json:
              example: |
                <<exampleReference1>>
    post:
      description: This API is used to create <<resourcePathName>>
      body: 
        application/json:
          example: |
            <<exampleReference2>>
      is: [responseMessage]

/songs:
  type: 
    collection:
        exampleReference1: |
          {"Songs":[
          {"SongID":1,"SongName":"London Dreams"},
          {"SongID":2,"SongName":"German Whip"}
          ]}
        exampleReference2: |
          {"SongID":1,"SongName":"London Dreams","Singer":"David"}
/artists:
  type:
    collection:
        exampleReference1: |
          {"Artists":[
          {"ArtistID":1,"ArtistName":"David"},
          {"ArtistID":2,"ArtistName":"John"}
          ]}
        exampleReference2: |
          {"ArtistID":1,"ArtistName":"John","D.O.B":"27 July 1978"}
/albums:
  post:
    body: 
      application/json:
        example: |
          {"AlbumsID":2,"AlbumNameName":"German Whip"}
    is: [responseMessage]

4.0 Video Tutorial on Traits

Now you know how to use resourceType and Traits with RAML.

Trait (computer programming)

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • How to Create a Real-Time Scalable Streaming App Using Apache NiFi, Apache Pulsar, and Apache Flink SQL
  • 7 Awesome Libraries for Java Unit and Integration Testing
  • Distributed SQL: An Alternative to Database Sharding
  • The Future of Cloud Engineering Evolves

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends: