Maintainable API Docs & Other Rainbow-Colored Unicorns

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.