White House shares API standards guide
In opening application programming interfaces to the public, WhiteHouse.gov wanted to build a repository that was maintainable and easy for developers to use.
"Before hands hit keyboards or anyone started writing any code, I think a number of people on our development team started thinking ahead to maintainability issues," said Bryan Hirsch, new media technologies tech lead in the Executive Office of the President. Hirsch spoke May 2 on a DigitalGov University webinar.
With that goal in mind, the team behind WhiteHouse.gov developed API standards and made them publicly available on GitHub. The standards have served as a useful reference document, said Leigh Heyman, director of new media technologies in the EOP.
"When we're working on the next iteration of any piece of API development work--working on exposing a new resource, working on adding new functionality, in the requirements gathering phase--we get out our API standards, and as we're specking out the requirements for new tickets we make sure we're building to standards and implementing particular standards as part of our requirements," said Heyman.
They also use their standards to double-check when something goes to code review and during quality assurance. If any work doesn't adhere to WhiteHouse.gov's API standards document, Hirsch and Heyman kick that work back to development before it can move forward.
Anyone can use the standards and Heyman said they invite people to fork the repository on GitHub, or propose changes for how they can make it more useful.
"As someone working with agencies on APIs, I would encourage agencies to basically take this and use it as is," said Gray Brooks, senior API strategist at the General Services Administration. "I think that it's a really good precedent that's worth following."
Any government agency can make a copy and personalize the standards for their own needs by forking the project from their agency GitHub account, said Brooks.
The API standards document may still change as pull requests and suggestions are coming in all the time, noted Heyman.
"We've gotten some really great feedback from the open source community, from the government community on the API standards," he said. And some of the those changes would require an API version 2.
While WhiteHouse.gov wants the API to incorporate the feedback and ideas, it also needs to be useful to the internal team. Right now they are navigating how to close issues in the issue queue and participating in the dialog without changing the standards to the point where they are no longer useful.
"My personal sense of where it's going--I think in the near future, we'll actually break this document into two where we've got standards and recommendations," said Heyman. One section will have WhiteHouse.gov's hard and fast API rules and the other will offer best practices.
"That's the stuff that we're considering for a future version of the standards, but we're not making it part of the top section because we're supporting an API right now that would break if we changed the standards," he said.
- go to the event page (includes archived webcast, slides and speak bios)