API Design and Documentation

Mar 12, 2013

Design
Children's building blocks letters spelling A P I.

At their core, developers want APIs for very straightforward, pragmatic ends. You should always design your APIs and document them with the goal of making it easier for developers to use them. Doing so results in greater adoption and a healthier, more successful API. The least efficient way to support developers would be to work with each interested developer individually on any question or problem that they have. Such a system would be a very inefficient use of your time as well as the developer’s. Instead, an API producer should bundle the API itself with useful and comprehensive documentation and tools such that any developer who stumbles upon the Web service can begin building with the API as easily as possible.

API design refers to the decisions that go into each of the structural and functional characteristics of the Web service itself. These include but are not limited to:

  • Protocol—What is the overarching specification used by the API?
  • Format—In what language or standard does the API return results?
  • Commands—What operations does the API support?
  • Endpoint Structure—What is the entry point to the API and the URL structure for possible commands?
  • Error Handling—How does the API respond when flawed queries are submitted?
  • Authentication—If users must authenticate in order to use the API, which system is used to manage the process?
  • Room for Growth—How is the API prepared for potential improvements or expansion in the future?

Search engines, communities such as API–Craft, publications such as APIEvanglist.com and ProgrammableWeb.com, and other resources listed below and in the Resources and Tools section all offer a wealth of specific guidance on each of these design decisions. The design of an API impacts every step of a developer’s experience and several overarching lessons stand out as core principles to guide you at each step.

  • An API should be easy to learn. You may be intimately familiar with your API but need to design for other teams and outside developers who may have never seen it.
  • Your API should have clear, discrete functions. If it doesn’t, it may be too complex for a newcomer to easily digest.
  • Start with use cases. Sometimes, an API producer begins by trying to build an API for all of their data and either makes a bulky and complex API or is forced to cut corners in order to include everything. Instead, start the design process with specific use cases that you know matter most to potential developers and build sensible, straightforward APIs for those needs.
  • Use developer norms. The developer community has spoken, with a clear consensus often emerging about many design decisions. Though you should always weigh the merits on each side, when there are clear preferences of mainstream developers, it’s important to choose what the developer community prefers (not what you or your IT department might be used to).
  • Design should be common sense. Use standardized commands and common names; avoid in–house terms or custom schemas wherever possible.
  • Get feedback. Ask prospective developers what would work best for them.
  • Document, document, document! One of the most common complaints from developers is missing, incomplete, outdated, or otherwise lacking documentation.

Documentation

APIs are a service that your agency provides. Agencies are the API producers. Developers are the APIs users, and they need good, clear documentation. The goal of an API and its documentation is to stand up a utility that helps users be as self-sufficient as possible. This frees up the API producer from providing basic user support. By providing useful and commonly requested information up front, API producers allow potential API consumers to easily prototype and build new products with less friction and with more success.

API documentation consists of a range of instructions, examples, and other resources that should facilitate developers in as many ways as possible. Documentation should explain the purpose of the API as well as provide ample guidance for using the API such that developers at all skill levels can easily and comfortably use the service.

Each API is different and may be best served by combining particular elements for the documentation package. The most common elements include an API description, authentication details, sample queries, terms of use, and a feedback mechanism, but by including as many elements from the API Release Kit and /Developer Kit as your team is able to support, you better support the full range of potential developers and encourage the greatest adoption. With each element, seek to flesh out examples, potential questions, and any other needs that a developer might have. By doing so, you will earn the attention and appreciation of developers who can then greatly expand the value of your API.

Resources

Originally posted by Gray Brooks on Mar 12, 2013

GSA | Washington, D.C.

Mar 12, 2013