Enterprise Integration Zone is brought to you in partnership with:

K. Scott Morrison is the Chief Technology Officer and Chief Architect at Layer 7 Technologies, where he is leading a team developing the next generation of security infrastructure for cloud computing and SOA. An architect and developer of highly scalable, enterprise systems for over 20 years, Scott has extensive experience across industry sectors as diverse as health, travel and transportation, and financial services. He has been a Director of Architecture and Technology at Infowave Software, a leading maker of wireless security and acceleration software for mobile devices, and was a senior architect at IBM. Before shifting to the private sector, Scott was with the world-renowned medical research program of the University of British Columbia, studying neurodegenerative disorders using medical imaging technology. Scott has posted 27 posts at DZone. You can read more from them at their website. View Full User Profile

The API Lab

03.08.2011
| 5714 views |
  • submit to reddit

Promotion is a problem faced by every API developer. Long nights of coding have given form to the stroke of genius you had six months ago in the cafe. You’ve just written the API that will serve as the front door into your application. But how do you document this so that your peers will use it—and hopefully make you rich in the process?

Java had Javadoc, an innovation that managed to strike a surprisingly effective balance between ease of use and systematization (three cheers for strong typing and static binding). Web services “solved” the interface definition problem with WSDL, a standard only its authors could love (and some of these won’t admit to participating in conception). To the registry crowd was left the task of devising clever ways to document a SOAP API around the torturous abstractions of WSDL so that humans could grok it as effectively as the machines. Few would argue that their solutions were, well, solutions.

RESTful APIs neither benefit nor suffer from formalized approach and automation. Every so often WADL pokes its head up, only to be knocked decisively back into its hole in a community game of Standards-Whac-A-Mole. REST is—and indeed, has always been—a style that resists any formalism that threatens its simplicity and accessibility. For this, above all, the community deserves praise.

But this does leave a hole around documentation. APIs tend to be described-by-wiki, which can be great or just awful, depending on a developer’s ability to write and discipline to update. Good ideas like ProgrammableWeb showcase both of these extremes; however, the site suffers in particular from out-of-date API descriptions which is too bad.

Outside of the eventual acceptance en masse of some kind of standardized wiki template for APIs (which I think is actually quite likely), we probably won’t see substantial change in API documentation soon. Minor changes, though, can still count for a lot, and it’s worth pointing these out.

Google, always an innovator to watch, create a lot of APIs. They recently published the Periodic Table of Google APIs, which as its name suggests is a clever way to visually categorize their API portfolio into groups like mobile, data, geo, etc. It’s a bit gimmicky, but it is also fun and actually inspired me to try some new Google APIs that I wasn’t aware of before.

So, isn’t it about time for more creative solutions around API documentation?

References
Published at DZone with permission of its author, Scott Morrison . (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Adam DuVander replied on Thu, 2011/03/10 - 7:49pm

This is a great history and summary, Scott. Thanks for mentioning ProgrammableWeb and where we could improve. I agree with your assessment of the industry. Certainly we tangle with poorly and undocumented APIs every day. Right now, documentation is probably the biggest area where providers can set themselves apart.

Kevin Dykes replied on Fri, 2011/03/11 - 1:44am

I agree that Programmable Web is doing a great job of showcasing API's. Developers in general though do a very bad job not only at documentation but at business-savvy use cases as well. So many business models are solely based on or at least extended through API business development approaches. I would like to see a standard section targeted at business users & example use cases on every API's documentation to target and appeal to the business leadership driving new integrations at many companies.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.