Click here to Skip to main content
Click here to Skip to main content
Technical Blog

Design and Document Your RESTful API Using RAML

, 23 Sep 2014 CPOL
Rate this:
Please Sign up or sign in to vote.
Design and document your RESTful API using RAML

Introduction

Creating documentation is one of the more tedious aspects of the software development process. Not that writing algorithms and object-oriented class hierarchies isn't tedious, but it often seems (at least to me) that writing plain text explaining your code is more tedious than writing the code itself. Also, if you consider yourself an Agile practitioner (as I do), you're always evaluating the time spent vs. value added whenever you write much about working software outside of and separate from the working software you already wrote.

I find myself constantly analyzing and re-analyzing the darn thing. Is it too long? Too short? Too wordy? Oversimplified? Too granular? Too vague? Should I have even attempted this?

I don't claim this conundrum is unique to me. It's one of the main reasons that many software projects are undocumented or under-documented. Because of this, a tool that helps you write clear, simple documentation, and saves you time doing it, is an invaluable find.

RAML is one of these fabulous creatures.

I was introduced to RAML by a colleague while working on an ASP.NET Web API project over the last few months. What I like best about RAML is that it solves multiple documentation problems through the creation and maintenance of a single file:

  • You can design and modify your API collaboratively without writing / re-writing any code.
  • The syntax is simple and to-the-point, reducing time needed to properly describe the routes, actions and parameters.
  • This document serves as a team "contract" of sorts throughout the development process. Server-side developers, client-side / mobile developers, and testers - everyone - can see and agree on the intended behavior and content of your API requests and responses.
  • When the project is done, you're left with an excellent artifact to hand off and / or publish describing exactly how your API works.

Now that's what I call valuable documentation. To get started, all you really need to write a RAML doc is a text editor and access to the spec. However the team over at MuleSoft has developed a superb browser-based editor for RAML, complete with spec references and "intellisense" of sorts. Best of all - it's free to use. They've labeled it as "API Designer" on their site; here's a sample:

I used it for the project I mentioned above; it was far quicker than writing a text-only version. Being able to click on and view the routes on the right side of the screen was also a really handy feature during various design and testing discussions. I found the API Designer to be a solid tool, and highly recommend it.

So the next time you kick off a REST API project, *start* with the documentation - and write some RAML.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Bryan O'Connell
Software Developer (Senior) SPR Consulting
United States United States
Bryan has been solving business problems with software and Agile methodologies for over twelve years. He has experience in all aspects of the software development lifecycle, having directed multiple projects from client initiation through product delivery, deployment, and growth as a team member, manager or independent contributor. Bryan is also a Certified Scrum Master and Manager.
Follow on   Twitter   LinkedIn

Comments and Discussions

 
Questionplease give some more details to use with .net webapi PinmemberMember 111985391-Nov-14 10:46 
AnswerRe: please give some more details to use with .net webapi PinmemberBryan O'Connell2-Nov-14 4:33 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web04 | 2.8.150305.1 | Last Updated 23 Sep 2014
Article Copyright 2014 by Bryan O'Connell
Everything else Copyright © CodeProject, 1999-2015
Layout: fixed | fluid