APIs, Documentation, Scalability, and My Social Web Startup

Last night I had a great idea! I've been thinking about and writing about the benefits of application of AOL's web service and API technologies for months--how the APIs let developers and start-ups link their innovative concepts for new user-centric applications with AOL's rock-solid, fully-scaled back-end resources--but I haven't really taken the time to try to bring it together into a single exemplary vision (and site) that illustrates what I've been talking about.

Microsoft and Developer Documentation

Several years ago, when I was devoting my full-time hours to leading development of Microsoft-based products, I found myself gaining a new respect for Microsoft (my background is mostly Unix) because of the quality of their developer tools and documentation, including Microsoft Developer's Network (MSDN). What also stood out for me was fairly large-scale working demonstrations of new technologies, such as the Microsoft .NET Pet Shop, which demonstrated a .NET implementation of Sun's Java Petstore.

High quality, detailed documentation of technologies that a company would like the broader development community to embrace is a critical element in determining the likelihood that the technology will become an enduring force. Beyond pure documentation, examples that illustrate how to use the technology are required. It can be very difficult to extract the exact line of code one must implement when all you have to go from is a highly detailed document that describes every parameter and property and method in the highest level of detail, with links and cross-references strewn throughout the hyperlinked documentation. You do need this level of detail, but developers also need some instances that show how to put together lines of code that perform a function.

At a slightly higher level are technology articles that examine a particular facet of the technology and demonstrate those facets through an example application. These articles provide the reader developer with a small working application or instructions on how to apply the code to achieve a defined objective. They can take these examples and modify them to accomplish the tasks at hand in their own current project.

I wrote quite a few articles of this type for Apress's CSharpToday site while I was leading Microsoft development, and more for the O'Reilly Network later on. This is precisely the type of article you'll find populating the Resources section of dev.aol.com -- in fact, our first AOL API specific article, "Building a Simple AOL Video Search API Application Using Ajax", by Paul Sobocinski, was published just last week. And there are many more articles in the pipeline.

Getting back to Microsoft: they do a superb job in all of these areas. Then, on top of all that, they add the much rarer feature of a full-scale exemplary application that demonstrates large areas of the new technology. This large application can be downloaded by the developer community, studied, individual components used as templates for developing new applications using the technology.

My Imaginary Web Startup Company

When I first saw MySpace.com, it seemed to me that, working with quality open source services and APIs, a few good developers could easily replicate its functionality within a few weeks. The core functionality of MySpace is fairly basic. Operationally, it's quite clunky and annoying! AIM Pages are so far superior to MySpace with respect to ability to integrate features that will run reliably (through modules, rather than through codes from who knows where that individual users cut and paste into their profiles, as is the case on MySpace).

I'd want to base my startup on a quality code base. Ideally, that code base would have already been tested in scenarios that proved that it was highly scalable. Here, unfortunately, is where a lot of excellent open source code is unproven. But, AOL's code? Yeah, after supporting tens or hundreds of millions of users under the AOL's old subscription model, you can say most of their code has already been proven to scale.

Of course, I need the API code to be easy to understand and apply. Hence, all my earlier discussion of Microsoft's documentation. AOL's APIs are documented in varying degrees--which is to be expected given the brief time the company has focused on being a provider of software to developers and other companies. One of the main goals of dev.aol.com is to bridge whatever gaps exist between between that highly-scalable code base and the developer community.

So, here's some of what my new imaginary/exemplary web startup will include:

• Web AIM: I'll use this for authenticating users (no user database of my own, all users who want an individualized experience on the site will need to use an AIM screen name). My site will start with like 80 Million members. That's cool!
• AIM Pages: a module will identify each user's preferences with respect to my startup site; and the module will allow the users to update their AIM Page with data from my site, similar to an RSS feed
• MySpace codes: there will be codes that provide linkage to the startup site for MySpace users and users of other sites that are customizable by users
• AOL Pictures: surely the users will want to view and share pictures!
• AOL Video Search API: and capability to search AOL Video, YouTube, MySpace, etc., for videos is surely a must!
• AIM Phoneline: a private phone line for receiving messages, and calls, connected right up to your AIM account? That sounds useful for finding out the latest news from friends.
• Mapquest: maps and directions will be critical; knowing how to get from place to place will be very important, especially when the schedule places and dates change
• Boxely and Open AIM: for AIM plugins, bots, a custom client?
• Userplane: for group interaction within the community and formation of sub-communities

The site will also integrate non-AOL APIs, but I'll get to that in future posts. For today, I've got a vision, a domain name, and I started seriously looking into the Web AIM code to figure out how I'll make my user login page. Not bad progress for Social Web Startup Day 1!

-- Kevin Farnham
O'Reilly Media