Thanks to the rise of open data initiatives and new laws, government agencies are increasingly looking to distribute their data using APIs. In an effort to support the development of APIs that enable those agencies to effectively serve their stakeholders and the public, the General Services Administration has published a set of API standards.
The standards were developed by 18F, a program launched by the General Services Administration (GSA) earlier this year to help promote digital innovation and improve service delivery within the federal government.
According to a post by 18F's Alan DeLevie and Eric Mill, "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."
The standards, which are housed in a GitHub repository, recommend the following:
Intuitive endpoints. Notably, "endpoint URLs should advertise resources," and it should be possible to determine what resource an endpoint represents without a detailed description or sample query string.
Use of HTTPS. To ensure security, privacy and compatibility, the 18F standards prescribe that new APIs employ HTTPS using TLS/SSL and recommend that non-HTTPs requests be disabled or redirected wherever feasible.
Unauthenticated access. While the 18F standards don't take a position on the requirement that developers register for API keys, the standards do suggest that a certain level of access be permitted without the use of an API key so that developers can more easily experiment with the API.
Exclusive use of JSON. According to the standards document, "Supporting JSON and only JSON is a practical default for APIs, and generally reduces complexity for both the API provider and consumer." Additionally, it is recommended that JSON data use UTF-8 encoding.
Robust error handling. Instead of simply providing an appropriate HTTP status code, assuming that the HTTP status code supports a response body, it should include JSON data with more detailed information about the error.
Support for data pagination. This entails providing metadata that enables consumers to determine the total number of results present and giving API consumers to the ability to request a specific subset of results.
Implementation of Cross-Origin Resource Sharing (CORS). Notably, the standards advise against the use of JSONP. "JSONP is not secure or performant," the document explains. "If IE8 or IE9 must be supported, use Microsoft's XDomainRequest object instead of JSONP."
In addition to its recommendations related to API design, 18F also provides guidance intended to improve overall developer experience.
First, it reminds agencies to design their APIs with common use cases in mind, such as bulk data export, and suggests that agencies design their APIs alongside implementations that will consume those APIs where possible. Additionally, it advises agencies to provide "an obvious mechanism for clients to report issues and ask questions about the API" and to set up a mailing list or developer blog through which clients can be notified of API updates.
Not Set in Stone
18F's DeLevie and Mill note that "what was once universally recommended about APIs just a few years ago may be dated today," and as such, their standards, which were forked from those created and published by the White House, are for the most part technology neutral and intended to serve as a "living document."
"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," DeLevie and Mill wrote.
What do you think of 18F's standards? What best practices do you think should be added to them? Let us know in the comments.