RESTful APIs: White House Sets The Standard(s)

Mark Boyd
Jun. 17 2013, 11:00AM EDT

The United States’ White House has developed a set of API standards they are hoping will be used across all government agencies. The standards were developed following a number of API releases, including the White House’s We The People API that allows citizen petition collection and lodgement. The new API standards document naming conventions, minimum requirements, and best practices for RESTful interfaces, while also acknowledging the importance of offering a “positive developer experience” through their API releases.

The standards have been published to github. White House staffers are hoping other government agencies will copy and personalise the standards to fit their API releases. Gray Brooks, senior API strategist at the White House’s General Services Administration told FierceMobileGovernment:

"As someone working with agencies on APIs, I would encourage agencies to basically take this and use it as is. I think that it's a really good precedent that's worth following."

Feedback from the open source community may lead to a later revision of the standards – with the White House’s API rules in one section and a second section introduced to document best practice ideals. For now, however, as the standards are already influencing the White House’s API development and have given rise to a number of unresolved pull requests and suggestions, the focus is on cementing the current version.

The standards are based on API work by Brian Mulloy, from Apigee, a drupal conference presentation, and a doctorate dissertation by Roy Fielding on RESTful architecture.

Some of the standards include:

  • Placing the API version number in the URL
  • Using plural nouns when identifying a resource in a URL
  • That error handling should include an HTTP status code, a message for the developer, a message for the end user, internal error code and links to more information.
Mark Boyd is a ProgrammableWeb writer covering breaking news, API business strategies and models, open data, and smart cities. I can be contacted via email, on Twitter, or on Google+.

Comments