Fork me on GitHub

/Developer Program

Your agency logo

API Design and Documentation


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:

Search engines, communities such as API–Craft, publications such as and, and other resources listed below and in the Resources 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.


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.


A Project of 18F