Click here to Skip to main content
15,031,835 members
Articles / Web Development
Technical Blog
Posted 23 Sep 2014

Tagged as

Stats

21.8K views
14 bookmarked

Design and Document Your RESTful API Using RAML

Rate me:
Please Sign up or sign in to vote.
5.00/5 (6 votes)
23 Sep 2014CPOL2 min read
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:

Image 1

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.

Comments and Discussions

 
Questionplease give some more details to use with .net webapi Pin
Member 111985391-Nov-14 9:46
MemberMember 111985391-Nov-14 9:46 
AnswerRe: please give some more details to use with .net webapi Pin
Bryan O'Connell2-Nov-14 3:33
MemberBryan O'Connell2-Nov-14 3:33 
Hi John,

Thanks for reading and sharing your questions.

To clarify, RAML and Web API are not currently integrated in any way that I know of. What I'm asserting here is that by designing your routes, requests and responses in RAML *before* writing any code, you'll save yourself a bunch of time when you do begin implementing the API, and hopefully avoid some amount of rework as well.

In terms of sharing the document, I think it depends on who you're sharing with. If you utilize the documentation property available in many of the RAML elements, simply sharing the .raml file might be enough for a fellow developer. They can use it as plain text, or load it into the API Designer tool I mentioned for easier navigation.

For someone less technical (like maybe a tester or a product owner), that might not be the best choice. We started using the raml2html package for Node.js for this purpose. It does exactly what it says; converts your RAML doc into an easily navigable HTML file. If you wanted to publish your API to a web site (public or private) this should be all you need.
Bryan O'Connell

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

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