Over a million developers have joined DZone.

Changing Requirements to Design in RAML 1.0

DZone's Guide to

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.

· Integration Zone ·
Free Resource

SnapLogic is the leading self-service enterprise-grade integration platform. Download the 2018 GartnerMagic Quadrant for Enterprise iPaaS or play around on the platform, risk free, for 30 days.

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.


#%RAML 1.0
title: HighSchool
version: 1.0
    !include datatypes/TeacherById.raml
            example: |
              { "courseid": [ "123", "456" ], "studentid": ["aa", "bb"] }
  description: Gets all courses and students handled by a teacher


#%RAML 1.0 DataType
type: object
  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.

Download A Buyer's Guide to Application and Data Integration, your one-stop-shop for research, checklists, and explanations for an application and data integration solution.

raml 1.0 ,api design ,types ,anypoint platform ,integration

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}