Changing Requirements to Design in RAML 1.0

RAML 1.0 's out of box feature "Type" is focused primarily on API Design for managed design.

Transcript

1. Changing requirements to design using RAML 1.0 Author : Arun V S
2. Changing requirements to design using RAML 1.0  Let us change a requirement to design using a powerful API Designer, an interactive online RAML editor. This article primarily focuses on a new feature - Types that is recently included in RAML 1.0 by leveraging the use of managed RAML fragments  Consider there is a requirement stating that "Create an API that displays list of courses and students for a teacher. A teacher may handle multiple courses. A student can also take up multiple courses."  Before starting 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 list of students under him/her and list of courses he/she teaches.
3. API Design using RAML 1.0  api.raml file at "API Designer" in "Anypoint Platform"(A product of MuleSoft, an iPaaS integration solution provider) is designed as shown below.
4. API Design using RAML 1.0 (Contd.)  In response, for the status code "200", the response must be array of students and array of courses.  We can define a type how the response should look like. 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
5. Base lining 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 so easily. Datatype 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.
6. Base lining the new feature of RAML 1.0 - TYPES  Click "Project" - "New Folder". Name the folder as datatypes(here). Right click datatypes folder, "New File" - "RAML 1.0" - "Type"
7. Base lining the new feature of RAML 1.0 - TYPES  Name the type file of your choice. Here it is named as TeacherById.raml
8. Base lining the new feature of RAML 1.0 - TYPES  In TeacherById.raml, define the type as object and specify its properties as shown below
9. Base lining the new feature of RAML 1.0 - TYPES  In api.raml, reference the "TeacherById.raml" file as a type. The modified RAML snippet is shown below.
10. A note to API Designers  RAML 1.0 is new and so cool that 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 know about RAML, check out this site: http://raml.org/  To know about API Designer in Anypoint Platform, please visit https://docs.mulesoft.com/api-manager/designing-your-api