You can provide the best API in the world, but if you don’t document it, the only developers that will use it are the ones that are paid to do it, or that enjoy pain. Most likely, your goal is to attract every type of developer: the hobbyists, the newbies, the freelancers, the paid employees, the student and more. The goal of your Documentation is to explain the API in a way that works for all of those types of developers, and all types of learners. The most friendly APIs provide all six of the ways described below to engage with their documentation.
A complete documentation set should try to include the following:
- Class Reference: A comprehensive listing of API functionality.
- Changelog: A reference of what changes in each API version.
- Code Samples: A set of examples showing typical API usage.
- Code Playground: An interactive explorer for trying the API live in the browser.
- Developers Guide: A conversational written guide to using the API.
- Articles: Tutorials and screencasts discussing different ways of using the API.
If your API is not open-source, then the class reference is the absolute go-to source for showing developers what classes and methods they can use. If your API is open-source (i.e. its a non-obfuscated Library of code), then this reference is a nice alternative to grepping through code and looking for methods. A reference can also be a great way to do a quick feature-check of an API - just by a quick skim of the top-level classes in an API, a developer can figure out if the API does what it wants it to do (or not).
The reference should show every aspect of an API - events, properties, options, methods, classes, and constants. It should also include every aspect of each of those. For example, a method should have arguments, a return type, and a description. A property should have the type and the default value, if there is one.
If your API has any notion of versions, and developers are able to access different versions of the API at any given time, then the reference should note the version differences in the reference. Similarly, if your API ever deprecates API objects, that should be very clearly shown. Also, since developers will refer to this document often, you want it to be searchable and sub-sections should be linkable.
When documenting your API, you must also document when and how your APIchanges. A changelog should list changes in behavior, new API objects,and deprecated API objects, with links to relevant sections of the referenceor blog posts. It should also list any developer-facing bugs that were fixed,and link to an issue tracker, if the bug was tracked there.
For the Maps APIs, we post the changelogs as wiki pages in the issue tracker project. That makes it easy to link to thechanged issues, and also comes with an RSS Feed, so developers can subscribe to any changes in the changelog wikis if desired. (Note: You should be also posting about changes to an announcements list).
It is great to explain the concepts behind an API and list all its objects in a reference, but when it comes down to actually using the API, nothing beats Sample Code. If a developer can see a bit of code, and know that the code works to produce the desired result, then they can immediately plug that into their code and modify as needed.
Good sample code should demonstrate actual (non-theoretical) uses of the API, should be commented, should be licensed appropriately (e.g. Apache). It should be runnable - developers should be able to prove that it works, before using it themselves. It should be linkable and searchable, like the rest of the documentation. And, if you really want to be able to scale up your repository of code samples, you should have a way of showcasing samples created by external developers.
It can sometimes be a lot of work for a developer to setup an environment to start using a particular API – sometimes, it’s so much work that they don’t ever do it. If a developer can start playing with API code live on your site, without any setup at all, and see what the code results in, then they’re more likely to get excited about an API and put in the effort to start using it. That’s why interactive code playgrounds are a nice complement to documentation.
Depending on whether you have a client-side, server-side, or HTTP API, the playground come in different forms. The Google Code Playground is a Sandbox for its AJAX APIs. The HTTP APIs had the Google API Explorer.
One of my favorite non-Google playground offerings is the Flickr API explorer, which wraps on top of their XML- RPC APIs, letting you specify all the different parameters and previewing the resulting XML in the browser. As a bonus, it even provides developers with suggested values for the parameters, based on their own photosets. Whenever I’m using the Flickr API and wondering if I can do something or how I can do it, I always hit up that Flickr API explorer first.
A developer’s guide is a walkthrough of how to use the API - it’s like how a teacher would explain the API to their students, but it’s penned down in digital ink (and there’s no talking back!). Some of those students will be new to the API, some will be new to web development entirely, and some will be old pros - the guide should work for all of them.
At the minimum, a guide should demonstrate how to get started using the API, bringing the developer from zero knowledge to a working piece of code. If they can get to that minimal working piece of code, then they will feel much more motivated to continue exploring the API using just the reference.
If possible, a guide can walk through all of the aspects of using the API, for the developers that learn the best through the instructional format.
While a developer’s guide should walk a developer through the basic usage of an API and its functionality, it can’t cover every possible use of that API in a coherent way. That is where articles and tutorials come in, to teach developers tangential or specialized uses of an API, like combining it with another service, Framework, or API.
Articles vary in form - some are like tutorials that step you from beginning to a final output, some are a collection of tips and some can be screencasts visually demonstrating a process. Each of those formats appeal to a different developer and work for different content, and it’s a good thing to experiment with the different formats and see what works for your audience and API.