DZone
Integration Zone
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
  • Refcardz
  • Trend Reports
  • Webinars
  • Zones
  • |
    • Agile
    • AI
    • Big Data
    • Cloud
    • Database
    • DevOps
    • Integration
    • IoT
    • Java
    • Microservices
    • Open Source
    • Performance
    • Security
    • Web Dev
DZone > Integration Zone > Changing Requirements to Design in RAML 1.0

Changing Requirements to Design in RAML 1.0

This article addresses a new feature of RAML 1.0, data types, replacing schemas to provide information for consumers and code generators to understand your API needs.

Arun VS user avatar by
Arun VS
·
Jun. 01, 17 · Integration Zone · Tutorial
Like (2)
Save
Tweet
3.92K Views

Join the DZone community and get the full member experience.

Join For Free

Let us change a requirement to design using a powerful API Designer, the interactive online RAML editor. This article primarily focuses on a new feature- Types- that was recently included in RAML 1.0, by leveraging the use of managed RAML fragments.

Consider there is a requirement stating: "Create an API that displays a list of courses and students for a teacher. A teacher may handle multiple courses. A student can also take multiple courses."

Before starting the design, we must carefully think what is the root resource here. From the requirement, we know that there are three resources - course, student, teacher. "Teacher" can be made as a root resource and the response must include a list of students under him/her and list of courses he/she teaches. 

API Design Using RAML 1.0

An api.raml file at "APIDesigner" in AnypointPlatform is designed as shown below.

Image title

In response, for the status code 200, the response must be an array of students and an array of courses. We can define a type for how the response should look. Defining a type should always be in a Root RAML section. If the response deviates from the type specified, then it will throw an error. 

Baselining the New Feature of RAML 1.0- Types

Data types serve as a way of replacing daunting schemas and provide even more information for consumers and code generators to ensure that they understand and meet your API data type needs.

We can also fragment them and manage them easily. Datatypes can be created as a separate RAML and included in the main file. While creating a datatype, always have a best practice of grouping all datatypes under a folder. In our case, we have only one. But when the requirements grow, defining and referencing them in the same file is not a good practice for managed design.

 Click "Project" - "New Folder". Name the folder as datatypes(here). Right click datatypes folder, "New File" - "RAML 1.0" - "Type"
Image title

Name the type file of your choice- here it is named TeacherById.raml- and click OK.

Image title

In TeacherById.raml, define the type as object and specify its properties as shown below.

Image title

In api.raml, reference the "TeacherById.raml" file as a type. The modified RAML is shown below.

Image title

RAML Snippets

For those who are interested in API Design in RAML 1.0, try out these samples by using it.

api.raml

#%RAML 1.0
title: HighSchool
version: 1.0
types:
  Collection:
    !include datatypes/TeacherById.raml
/teacher/{teacherid}:
  get:
    responses:
      200:
        body:
          application/json:
            type:
              Collection
            example: |
              { "courseid": [ "123", "456" ], "studentid": ["aa", "bb"] }
  description: Gets all courses and students handled by a teacher

TeacherById.raml

#%RAML 1.0 DataType
type: object
properties:
  courseid: string[]
  studentid: string[]

A Note to API Designers

RAML 1.0 is new and so cool that it encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices. I hope you have used Swagger specifications for API Design. You can also even convert your Swagger specifications to RAML.

  • To learn about RAML, check out this site.

  • To learn about API Designer in Anypoint Platform, please visit here.

Design Requirement API

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • Modern REST API Design Principles and Rules
  • Debugging Deadlocks and Race Conditions
  • How to Leverage Method Chaining To Add Smart Message Routing in Java
  • How to Hash, Salt, and Verify Passwords in NodeJS, Python, Golang, and Java

Comments

Integration Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • MVB Program
  • 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:

DZone.com is powered by 

AnswerHub logo