Application programming interfaces (APIs) are software components that allow direct computer-to-computer communication. They are one of the critical building blocks of the modern IT enterprise. Major technological shifts like cloud computing platforms and software-as-a-service require organizations to produce and consume APIs effectively and securely. GSA has been using APIs for many years to integrate internal systems, connect to trusted partners, and share data with the public.
In December 2018, we accomplished a major milestone in our API strategy: the implementation of a set of API standards to streamline the development of high quality, secure, user-focused APIs. We are planning several more initiatives to advance GSA’s API strategy in the coming year, including an API security guide, API playbook, API training sessions, and updates to the GSA developer portal.
When GSA teams need to publish APIs, they want to focus on their business objectives without being bogged down by numerous technical and design decisions. The GSA API standards provide a roadmap and practical guidance for teams to follow when publishing APIs. The standards include 7 mandatory items for all public APIs, and one additional mandatory item for all new public APIs.
Benefits of API Standards
These standards save significant time and money for GSA’s business and IT organizations by streamlining of API design and implementation. The standards give clear guidance to address many of the challenges and decisions that organizations face when they begin producing a new API.
The standards help new users of GSA APIs, who want to quickly explore an API, clearly understand its functionality, and implement with a minimum of friction. The standards require high quality documentation, which can reduce the time it takes new users to start using an API.
For existing users, the standards address the issue of adding features without breaking their existing functionality by requiring versioning of APIs and providing clear implementation guidance. The standards also require a clear and supported feedback mechanism, and recommend methods for responsive API support when issues arise.
Making the Right Thing the Easy Thing
The API standards rollout was led by the Chief Technology Officer (CTO) organization and the GSA API Working Group of API developers, business owners, and users. Our guiding philosophy was to “make the right thing the easy thing” and take the pain and expense out of implementing the standards by:
- Providing tools to smooth the way. The api.data.gov API management service allows for the implementation of many of the standards without a change to the original API. This is because it is implemented as “proxy” between the APIs and the API consumers.
- Engaging with API teams to finalize the standards. While we were finalizing the standards, we communicated frequently through the email listserv messages and hosted open “office hours” where many API owners came and discussed the new standards.
- Assessing the impact ahead of time. We created a review checklist and guided the API owners in an assessment of the agency’s public APIs against the mandatory items. This assessment showed the level of effort that would be required for APIs to comply, and led to several updates to make sure the final standards were realistic.
API teams were actively engaged throughout this process, and they told us that our level of communication and assistance was valuable to them.
The Path Toward the Goal
GSA’s API standards were drafted in early 2017, based on the 18F API standards used by GSA’s 18F team. The new GSA standards started in “beta” status, with several groups testing them and providing feedback.
In fall of 2018, the CTO team and API Working Group led an effort to update the directory of GSA’s public APIs on the GSA developer portal. They identified all API owners and invited them to join the working group, pushing membership to over 100. This larger group worked together to update the standards based on best practices and practical realities of GSA API teams.
Supporting The Standards
The final revision of the standards went into production in early December 2018. The CTO team and API Working Group will continue to support API teams as they begin implementing the standards by:
- Hosting regular office hours to answer questions and demonstrate tools and techniques.
- Publishing technical guides.
- Performing pair programming with teams.
- Conducting training.
- Sharing tips and tricks with the API Working Group listserv.
GSA’s API Strategy
The updated API standards are an important step toward implementing GSA’s API strategy. The CTO organization also recently enabled self-service API documentation hosting directly on the GSA developer portal at https://open.gsa.gov/api. Additional tools and resources to GSA API owners will be rolled out in 2019, including several technical guides and playbooks.
These are part of GSA’s 3-pillar approach for implementing the API strategy:
Pillar 1: External Customer Experience
Providing APIs and API documentation that fulfill the needs of customers. Designing from a user-focused perspective, rather than technology-focused one.
Pillar 2: Internal Engagement
Building a community of API owners and practitioners inside GSA to develop APIs in a consistent fashion.
Pillar 3: Technical Architecture
Designing technology solutions for developing and hosting high quality APIs. Creating technical guides to assist teams in implementing APIs that follow the GSA API standards.
—
For more information about APIs, read APIs In Government. For more information about GSA’s API standards, contact cto@gsa.gov.
