We recently released the first version of our API Standards — a set of recommendations and guidelines for API production. It is our intention that every 18F API meet these standards, to help us ensure a baseline quality and consistency across all APIs we offer now and in the future.
These standards guide the user-facing implementation details of an API. Wherever possible, the standards prescribe a goal instead of a specific technology. What was once universally recommended about APIs just a few years ago may be dated today. For example, while the best issue tracker may change every couple years, the need for an obvious point of contact to the API producer is more enduring.
The standards are generally technology-neutral, with a few specific opinions when warranted. For example, our standards don’t allow for the use of JSONP, as it raises security and performance concerns.
Though these standards are part of a living document, a focus on goals—and not on tools—will increase their shelf-life. By writing these standards under a goal-oriented and “sane defaults” approach, we hope they help us achieve API objectives that will never change: utility for the users and respect for their time and effort.
We began drafting our standards after forking the White House’s own API standards. By publishing their standards in the open so others could benefit, the White House set an important example—one that we greatly support! Similarly, we invite you to fork our API standards and modify as needed for your own organization’s use.