Any website that offers an API should also provide a section for developers that includes documentation and information about the services provided. This information is vital to the success of your API - lack of information, or the wrong information, means that developers won’t have what they need to use the API successfully. There are some low-barrier approaches to creating this section that will help to create a vibrant and active developer community around your API.
A great example of how this information can be useful is in the government space. The new Digital Government Strategy requires all agencies to create and publish a new developer section at /developer of all agency websites. This is a huge undertaking that has the potential to standardize how and where developers go to find information about government APIs. The key to the success of this effort with be making sure that developers know where to find the information and that the information they need is available.
The first challenge developers run into when building with APIs is discovering what web services are available.
An emerging standard is that all ‘developer’ information is published at /developer. This is a common-sense approach that every organization can follow, and will make the web a more navigable place for developers.
The goal of the /developer page is to make it easy for users to find the APIs your website offers, and understand how to use them. But it should also include any other general information developers need to know about, including:
- Authentication/Authorization: if your API makes use of access control mechanisms, you should have a section dedicated to documenting the type and how to use it. If you require developers to obtain a key or sign up for an account, make this easy to find and require as few steps as possible.
- Forums or other community information: though you might not provide support for free users of your API, you should still create or sanction some sort of community for your users. Google groups is often enough. This will be invaluable to people who run into issues - they will be easily able to find help, improving the chances that they will be a successful user.
- API system architecture, including general design patterns: provide at least a page describing the design of your API, including the general design (is it RESTful or parameterized?) This is a great place to discuss any behind-the-scenes management strategies, like load balancing or request throttling, that will impact the developer but might not be apparent.
Automatic API Description and Discovery
You need to provide both a human readable developer section, but increasingly organizations are looking to provide a machine-readable source of API information. The goal here is that applications can begin to connect directly to each other without needing a developer to interpret the documentation. In practice, a machine readable format for API description gives developers a better set of tools for using your API.
A great example of this is Swagger which uses a machine parsable API description file to build a rich developer interface for an API. Developers can read the documentation and easily make a service call in one place. This decreases the time it takes for developers to learn how to use your API and makes it easier to build a community faster.
API documentation is the core of any /developer page. This is the place where developers go to find out how to actually use your API. You should plan to have a dedicated documentation page for each API endpoint (url), as the information for each will be unique. For each API, plan on including the following information:
Brief description and anticipated usage. How do you envision your users making use of this API? What’s its purpose? Describe at a high level what you can do with it.
- Authentication: is authentication required? If so, describe the authentication system in brief, with a link back to the more complete docs.
- Parameters: if the API accepts input, describe the parameters with example values.
- Return: what does your API return? What is the data format, and what are the return values? What is the standard interpretation of the return?
- Errors: when something goes wrong, what happens? How should developers interpret the errors, and what should they do about it?
Another tool that can be really helpful is a GUI API query builder. If you're using Swagger, this can be easily generated using a number of tools. However, it should be relatively trivial to build this and host it using your official API library. One of the really nice things about this tool for developers is being able to see the expected values for each request parameter — its a lot easier to see it in action than try and plow through the developer documentation to figure out what possible values are.
Let developers quickly see real example responses, in ways they can experiment with and vary to explore the range of data you've got available. If your API requires authentication, provide a demo account key or tools for generating queries and live responses using the developer's own access keys.
An example of a great API query tool can be found at the New York Times: http://prototype.nytimes.com/gst/apitool/index.html.
Lastly, its important to link to any dependency libraries your API relies on. This might include XML or JSON parsers, or if you are using other third party tools, say RDF, links to recommended libraries for consuming the returns.
There are a few great developer pages out there that can serve as a model of what to do. These stick roughly to the points above, but every API is different, and so every developer section should be a bit unique.
- New York Times: a great developer section with lots of information up front, as well as complete documentation and helpful tools for consuming the API.
- ESPN: The newly launched ESPN developer center does a great job of providing all the right information for developers.