Changing Requirements to Design in RAML 1.0

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.

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"

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

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

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

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.