Maintainable API Docs & Other Rainbow-Colored Unicorns

Tools and Techniques
Location: D139/140
Tags: api, json, rest
Presentations: external link,
external link
Average rating: ****.
(4.33, 12 ratings)

Today’s REST API landscape is littered with inaccurate documentation, production APIs that break in the wild, and developer tears. API documentation is frequently out of sync with the API that’s actually running in production, and it can often be weeks or months before anyone notices—or developers complain.

The post-WADL world is bleak. Some developers think they should be publishing a WADL, but no one wants to. Other API developers simply awaken in the night with the possibility of an unhappy dev hating on their work due to a doc bug gnawing at their soul. No sane person speaks of WSDL 2.0 in polite company.

Unico, an open Domain Specific Language, or DSL, can bring harmony to this chaos. Using natural-language prose with just a handful of keywords, Unico can drive documentation generation, executable test case creation, JSON Schema, and if desired, Relax NG schema to use in generating WADL.

With a single, human-maintainable set of documents defining an API, business stakeholders can manage the key components necessary for supporting an API program without having to know more than a little HTTP.

In this session, a simple API will be created in real-time using Unico, leaving attendees with enough insight to understand how they can get their own API distribution under control and start sleeping better right away.

Photo of Neil Mansilla

Neil Mansilla

Mashery, Inc.

Neil Mansilla is the Director of Developer Products and API evangelist for Mashery. He is a passionate software engineer and tech entrepreneur. Neil previously founded several web and software companies in verticals including search, e-commerce, real estate and healthcare. He is responsible for helping developers discover, learn and utilize the platforms on the Mashery API Network.

Comments on this page are now closed.


Picture of Neil Mansilla
Neil Mansilla
08/01/2011 2:35am PDT

The source to I/O Docs Node.js has been posted here:
Picture of Neil Mansilla
Neil Mansilla
07/29/2011 7:18am PDT

Thanks so much for coming and participating. There were some really great conversations about the exciting world of API docs. :)

Slideshare is below. I’ve also added a slide with the URLs I had loaded in my browser.

Picture of Peter Banka
Peter Banka
07/29/2011 5:38am PDT

Great presentation style. Fluid. Informative.

Picture of Augustina Ragwitz
Augustina Ragwitz
07/29/2011 4:18am PDT

Really enjoyed this presentation! My company’s API docs are awesome but difficult for devs to maintain. I got exactly what I needed from this presentation, pointers to a tool that could possibly help us!

Picture of Fred Willerup
Fred Willerup
07/29/2011 3:42am PDT

Really great stuff. Great interactive discussion afterwards.