[uf-new] A microformat for web API descriptions

[Greg Brail]

APIs -- Internet-based web services that take advantage of HTTP, XML,
JSON, and many of the REST concepts -- have become prevalent on the
Internet, with huge growth in APIs used to construct web apps, mobile
apps, embedded devices, internal web services, and other things. Companies
like Twitter, Netflix, Twilio, and others have built big businesses on
their APIs.

Existing APIs today typically use the HTTP protocol, JSON, and / or XML.
Some use SOAP but most use aspects of the "REST" architectural style. Some
of these are built using fully Roy-Fielding-approved REST complete with
hypermedia links, while others take advantage of the HTTP protocol without
being fully hypermedia-driven.  It is not our intention to promote or
prevent a particular style of API, but to make it possible to discover and
use APIs that follow a variety of styles.

APIs are nearly always accompanied by documentation that describes how to
use them. Thanks to the proliferation of HTTP-based APIs that make use of
XML and JSON, armed with suitable documentation and a few tools a
developer may be able to quickly make and try API calls right away just by
looking at the docs.

A microformat or microdata standard for API description could potentially
have many benefits to the API community. For instance, API descriptions
could be queried via search engine; specialized search engines could be
developed to discover new APIs and find changes to existing APIs; and
tools for testing and learning APIs could be developed based on the HTML
markup.

At Apigee, we have been helping providers and consumers of APIs through
tools that make it easier to use APIs, and infrastructure that makes it
easiser to expose APIs. Enhancing the discoverability and usability of
APIs is important to us as a company and we are interested in contributing
to an effort to research possible semantic formats for API data.

I plan to gather examples of existing API documentation and brainstorm
some ideas on the Microformats Wiki, as appropriate. Let me know if you
have ideas or would like to contribute -- thanks!