Take a gander at our /Developer page!
By Gray Brooks
A growing trend both inside government and outside is to have a simple welcoming page for outside developers who may be interested in your team’s efforts. This material is often located at website.gov/developer 1 and points visitors to technical material that developers may be interested in, especially APIs. Collecting technical documentation in one place facilitates the developer experience, ensuring that they can find and begin using APIs with as little friction as possible.
Believing in this best practice, we’re launching 18F’s /developer page to provide a consistent and friendly starting point for other coders — both in the public and within government. There are two main sections, one for our APIs and another for 18F initiatives that are targeted to this community. There’s a good bit there but we hope you’ll check back often as we add more APIs…a lot more APIs!
as recommended in the Digital Government Strategy
Midas: A Marketplace for Innovation in Government
By Joe Polastre, 18F and Matt Chessen, Department of State
Midas is an online platform that brings to life the vision of an “Innovation Toolkit” for government. It is a marketplace of skill building opportunities which matches people to projects that they’re passionate about. You can think of it as “kickstarter for people’s time”.
The concept of an Innovation Toolkit started as a Presidential Innovation Fellows project to give federal employees a place to work on innovative ideas across government that may occur outside their normal job or management chain. The Department of State’s Office of eDiplomacy teamed up with The White House Office of Science and Technology Policy to prototype a crowdsourced marketplace for innovation.
The History of Midas
To understand why the State Department was interested in such a project, first imagine that you’re an enthusiastic federal employee that has lots of ideas for government to better serve its people and businesses. One such group of feds is foreign service officers, especially junior foreign service officers who spend their first few years performing consular work. They are located around the world and typically process visas and passports full time. Foreign service officers are highly educated and trained individuals — often with advanced degrees and significant work experience. The question was posed: how can we leverage this untapped potential of the federal workforce to make meaningful progress on innovative projects? And how do we provide professional development opportunities to both local and remote workers that want to build their skills and advance in their career?
From June through December 2013, through the Presidential Innovation Fellows program, we conducted numerous user interviews and meetings with stakeholders at the State Department. We met with foreign service officers, supervisors, and country desk officers that coordinate activities in each region. From these interviews, tests, and prototypes came Midas — a marketplace for projects and opportunities. At State, they started calling it “crowdworking.” (The internal website at State is officially called “Crowdwork”.)
How Midas Works
Midas consists of three main components — Projects, Opportunities, and Profiles — all of which are connected through skills and topics of interest.
When employees sign up, they get a profile on Midas (which can be imported from existing services such as LinkedIn). Profiles contain a list of skills as well as topics that employees are interested in or passionate about.
Projects are a container that holds the discussions, events, files, and participants of a proposed activity. Projects also have skills and topics associated with them. This is where work can be coordinated. A project doesn’t have to be a project in the traditional sense; it can be a "tiger team", a community of practice, or an interest group (for example, a group of people that get together to volunteer for a particular cause outside of work).
Opportunities are crowdsourced tasks that need volunteers. Opportunities are also associated with skills and topics. An opportunity can be part of a project, or a standalone need. These can be accomplished in as little as 15 minutes, or could be as consuming as a 6 or 12 month full time detail of the employee to another office.
Midas in Action
Midas is currently being piloted by the Department of State [GitHub] and the Department of Health and Human Services [GitHub]. Midas is also a key component of the Office of Personnel Management’s GovConnect initiative, which is part of the President’s Second Term Management Agenda. Through GovConnect, agencies can experiment, prototype, and implement new workforce engagement programs, like Midas.
Crowdwork, the name of the Midas system at the Department of State, received the NextGen Exemplary Group Award. The award will be celebrated at the NextGen Training Summit on July 23, 2014 in Washington, D.C.
Midas for You
At 18F, we are now offering Midas to federal agencies as a Software as a Service. Any agency can test out Midas quickly, and focus on the programmatic aspect of “crowdworking” in their community rather than get bogged down in the details of acquiring and standing up the technology.
Strategic Benefits of using Midas:
- Leverage capacity of remote offices to accomplish more within an agency
- Augment existing teams (both within and outside agency) with skillsets needed but not currently available within the team
- Provide additional professional development opportunities to employees that match their interests and passions
- Improve employee morale and engagement
From Day 1, Midas has been available as open source on GitHub. It is free for anyone to download, install, and use. All of our issues, features, and bugs are out in the open. Management of Midas uses agile methodologies and development is organized into sprints.
Come check out Midas for yourself on GitHub, and see how federal employees are working more organically, across traditional silos, and more collaboratively to improve government.
Hot off the press: 18F’s API Standards
By Alan DeLevie and Eric Mill
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.
Intro to APIs: Working with URLs, JSON, APIs, and Open Data — Without Writing Any Code
June 27 @ 9:30am - 11:30am
GSA’s digital teams are offering a user-friendly intro course to APIs. Regardless of your skill level, you will walk away from this lesson understanding what APIs are and how developers use them.
Every federal agency is scaling out its use of APIs so even if they are not a part of your normal daily work, learning what they are, how they work, and why they are changing government.
This is an in-person, interactive session led by Eric Mill, a key developer on GSA’s 18F team and an expert in open data and government technology. Again, this session is designed so that even complete beginners will be able to follow along, so if anyone you know is wondering what all the fuss about APIs is about – this is for you.
Who should attend:
- System Owners
- Digital Engagement Staff
- CIO and CTO Staff
- Government Staff Interested in Open Data efforts
- Anyone Who Is Curious!
What you’ll need:
- A laptop, with a working connection to the public Internet
- A recent version of Firefox or Chrome
- An extension installed for Firefox or Chrome to view JSON in your browser (please install beforehand)
Links that will come up:
Friday, June 27, 2014
9:30 am - 11:30 am
GSA Central Office
1800 F St NW, Washington, DC 20006
Announcing The /Developer Program: A New Hub for Federal API Creators
By Leah Bannon and Gray Brooks
We recently launched our /Developer Program (pronounced “slash developer”) to help federal agencies develop useful, robust APIs. The Program is a collection of educational resources, opportunities to engage the community for help and feedback, and tools that can help you build APIs — essentially an ever-growing knowledge base curated by 18F. We affectionately named the /Developer Program after the common practice of providing API documentation and links on government websites at website.gov/developer1.
We use the term “launched” liberally though, because this has been a labor of love over the past year or more for the digital gov community. APIs are basically a way for two programs to share information or perform an action2, and they continue to play an increasingly fundamental role across the web. There are now almost 100 developer hubs that provide access to hundreds of web services across government.
Whether you’re new to APIs or have years of experience, the site’s list of educational resources can help you better understand the role that APIs can play for your agency as well as explain them to your colleagues. These resources include API definitions and analogies, training, best practices, talking points, FAQs, and case studies in case you need inspiration or examples.
Community & Collaboration
The best way to improve and promote your agency’s APIs is to get involved with API producers at other agencies and the developers who use your APIs. The site offers links to meetups and other API events, as well as our API Usability Testing program where agencies demo their APIs to real users and customers to get their feedback. We also provide examples of excellent government APIs, sample policy and contract language for building APIs, and links to good API standards and guidelines.
Tools & Resources
We are compiling a list of open source tools and resources to help you actually build your APIs, including data converters, standards, developer kits, and more. There are hosted tools that can take data in a spreadsheet file and instantly make it available as a RESTful API. For enterprise needs, a powerful API proxy offers key management and analytics functionality for any agency’s use.
Please feel free to provide feedback and suggest additional resources; the entire /Developer Program is an open source project on GitHub.
This was recommended in the Digital Government Strategy.
Packaging Up API Usability Testing for Agency Re-Use
By: Gray Brooks
Over the past year, a GSA collaboration has seen a project that offers API Usability Testing to federal agencies go from the pilot stage to a regular, robust series. Already, 13 agencies and programs have participated, and several more participate with every monthly session that passes. The best examples from across the government have made clear that one of the most important tasks of API producers is to regularly engage their developer community and listen to what they have to say. But just encouraging agencies to do this only goes so far.
In addition to offering any federal agency direct support by hosting them at an API Usability session, we’ve also been working to document and open-source the actual process itself. We want every agency to realize how readily they can scale out these exercises on their own. Within the API Usability Kit, agencies will find proposed schedules, email and handout templates, an overall guide, and frequently asked questions. But since each component is itself an open source project, anyone can easily edit any page or fork the entire project.
As we move forward, it’s our hope that you’ll join us — in person for API Usability sessions for your program, but also through open collaboration with the material that we use to run the program. Help make this program better! Anytime you have a suggestion, all you have to do is click the ‘Edit’ button in the sidebar and propose away.
As with any good open-source project, we eat our own dog food and strive to ensure that this program grows through an open, organic process. We’ll continue to edit and build out the resources that make up the API Usability Kit. Through that, we believe we can ensure the best product for agencies and the best results for the final customer — the people of the United States.
See also, Gray’s presentation from last week’s 18F Demo Day:
Slides from the Inaugural 18F Demo Day
The presentations given at the inaugural 18F Demo Day on May 9, 2014 are online and available at Speaker Deck. If you would like more information on any topic, please feel free to contact the individual speaker.
Hacking Bureaucracy —
FBOpen & Procurement Tools —
Midas / Innovation Toolkit —
API Usability Testing —
SAM.gov “Pizza Tracker” —
Robert Read & Navin Vembar
CAP Communicart —
We the People: User-Centered Design —
Hacking Bureaucracy: improving hiring and software deployment
By: Greg Godbout and Noah Kunin
When asked what it is we do, one quick answer is, “We’re hacking bureaucracy.” While it may sound provocative, it isn’t.
In the movies, hackers are often dangerous criminals who break into large systems, but in the software development community, “hacker” describes the way someone thinks and works rather than a malicious activity — hackers are problem solvers. We consider ourselves hackers in that positive sense: productively disruptive and curious. (See “What is a Hacker?” by Bruce Schneier for a wonderful definition.)
It’s not enough for us to just build software inside the Federal Government. Such an approach may bring short term gains, but it won’t drive long term positive change. At 18F we’re integrating our style of software development with the many departments and employees of the federal bureaucracy. This is the human platform on which we build our software platforms.
When we launched 18F internally in December, we decided to start with two initial big and challenging projects: improving the efficiency and agility of (1) the hiring process and (2) the software deployment process. Building our “start-up” inside the federal bureaucracy meant first integrating with the federal bureaucracy.
Historically, hiring and software deployment practices inside the Federal Government have posed significant challenges for agile and user-centered software development practices. These processes need to take weeks, not months.
18F is approaching hiring and software deployment in the same agile, open, user-centered way that we approach all of our projects:
- Find innovators inside government who have solved similar problems
- Engage stakeholders and users early and often
- Set up a minimum viable product to get started quickly
- Give real users the process/solution from the beginning
- Learn and iterate our approach
- Stay aligned with the rules of the bureaucracy
- Formalize the process/solution for reuse
The initial results have been exciting. Collaboratively, we’ve significantly improved turnaround times for hiring and secure deployments. We’ve reduced the time to hire by 70%, and the time to deploy software by 80%, and many of our products are now in continuous deployment. Despite the constraints of the federal bureaucracy, continuous iterative improvement is possible. These processes and policies are now being formalized and we intend to make them repeatable and useful to the rest of the Federal Government.
Our colleagues, who have been innovating within the government for years, have been excellent teachers. These results are not possible without the strong partnerships and leadership provided by multiple teams inside GSA: the Administrator’s Office, Human Resources Management, Office of the CIO, Office of the Senior Information Security Officer, and many other technologists throughout the Federal Government. In the spirit of the collaboration that helped to achieve these results, we plan to share the details of our HR process and software deployment process publicly.
This is the first of an ongoing series of blogs where we share the details, methods, and stories of how 18F hacks bureaucracy.
You can also view our "Hacking Bureaucracy" presentation from 18F Demo Day on May 9th:
18F Shows What Is Possible In Government With FBOpen API
Cross-posted from API Evangelist, by former Presidential Innovation Fellow Kin Lane.
There has been some great coverage of the new group of tech specialists out of the GSA, dubbed 18F. According to their own home page, 18F:
…builds effective, user-centric digital services focused on the interaction between government and the people and businesses it serves. We help agencies deliver on their mission through the development of digital and web services.
I know most of the team members from my work with the GSA, and my own time (albeit short) as a Presidential Innovation Fellow, and I am extremely optimistic about the potential of the team. This optimism is being seriously validated after looking through the group’s recent release of the FBOpen API, which is a simple API resource to get access to opportunities to do business with the U.S. Federal Government.
Use Existing Tools
18F demonstrates their tech chops by not re-inventing the wheel when it comes to designing and developing the FBOpen API. After they downloaded the existing business opportunity XML dumps from FBO.gov, they employed Apache Solr to develop a thin API layer on top of the files. Solr does two things well, it provides a REST interface on top of document stores, and supports the Lucene query syntax, which provides a powerful query interface on top of the simple API. Beyond Solr, 18F also used Apiary and Github, to cobble together a platform for API operations, demonstrating their dedication to agility and speed.
The FBOpen API interface adheres to API simplicity by providing logical, versioned URI for accessing the government business opportunities, with a query and data source parameter allowing you to tailor the source of your query. Then you can filter by noncompetes or closed opportunities, as well as controlling the number of results returned, including common pagination controls developers are used to when working with APIs. FBOpen API does one thing, and does it well—the calling card of successful APis.
Modern Design Lifecycle
Again, demonstrating their grasp of modern technology, 18F employs Apiary to model and design the FBOpen API interface—using API Blueprint allowed them to define the API interface in markdown, then deploy a mock interface, interactive API documentation and code samples in a variety of languages. This approach to designing APIs in government is the future for not just providing a machine readable definition of the API, but delivers the documentation and code necessary to onboard any developer in minutes—increasing the chances the API will be integrated with.
Open By Default
The FBOpen API sets the bar for all government APIs, by making sure not just the API is public and accessible, but so is the API design, source code and underlying tooling—allowing anyone to deploy an instance of the FBOpen API. Since FBOpoen is built on Solr, publicly available XML data source, and published on Github, anyone can download or fork, and deploy their own instance of the FBOpen API. This is the definition of an open API.
Central Key Management With api.data.gov
Before you can make calls on the central FBOpen API instance, you must obtain an API key from api.data.gov. This should be standard business operations for ALL federal government APIs. Developers shouldn’t have to manage separate accounts with each agency, they should be able to request credentials in a single location, and use across all APIs they consume within in the federal government. api.data.gov uses API Umbrella, an open source API management solution developed by National Renewable Energy Laboratory (NREL), and is employed by the GSA in the common API infrastructure available to all agencies.
Read / Write APIs in Government (kindasorta)
I started to cry when I saw that there was not just a GET method for FBOpen, but here was a POST method, allowing for users to add or update opportunities via the API—then I saw it was disabled, and the tears dried up. The option is only available if you deploy your own instance of the API, which in my opinion actually represents the future of read / write APIs in government. I just don’t think government can move fast enough, and manage the responsibility of write APIs in all scenarios, and providing open source APIs like FBOpen, that anyone can download, install and allow for adding and updating data can bridge this canyon. If enough trusted instances of the FBOpen can be established outside the federal government firewall, agencies can make their own decision around which sources they want to trust and pull opportunities back into internal systems. With proper certification of API deployments by our government, APIs lie FBOpen can share the load of managing data with private sector, without the risk that comes with doing it all internally.
Make Gov APIs Better with User Experience
Cross-posted from DigitalGov.gov. By Jonathan Rubin & Gray Brooks.
APIs and User Experience go together like gummi bears and ice cream.
An API is a product just like a car, a website or a ballpoint pen. It’s designed to help someone do something. Products are either designed well—they meet expectations and deliver value—or they are designed poorly and create frustration and confusion. Inevitably, bad products are abandoned without a thought, like an old T-shirt with holes in it.
So for the past few months we have been taking APIs from USDA, FEMA, OPM, and other agencies and improving them via User Experience evaluations. We bring together agencies and their customers—private-sector developers who use APIs every day—and ask the developers to maneuver the APIs and documentation. These developers provide a live critique of the APIs and identify problems and stumbling blocks to using them.
Bing! Instant and unfiltered customer feedback.
And who are we? We’re two GSA programs—DigitalGov User Experience Program and 18F—who care about creating better digital products. We improve federal systems and teach people about user research, all in one morning.
The promise of APIs is incredible and their widespread adoption is a key part of 21st century government. But APIs are only worth the sweat and tears that go into their creation if people can use them. Our program has helped more than a dozen agencies realize the benefits of User Experience evaluations.
And we’ve learned a lot along the way:
1. Developers want to start using the API immediately.
No matter who they are, developers begin to lose interest fast if they can’t begin using your API right now. Include links to the endpoint at the top of your documentation. If you require API keys, the registration process must be self-service—requiring someone on your team to act in order for the developer to be able to get started at all, will cost you more developers than you’ll keep.
2. Interactive documentation has become the norm.
There are countless free and easy-to-use options for offering interactive documentation or data explorers that let developers build and test queries. You’ll want to include these since the best way for developers to understand how to use your API isn’t to read more documentation, but rather to see the API in action.
3. Don’t. Speak. Government.
Avoid acronyms, insider terms, and obscure abbreviations. You’ll document a better API for all users, including traditional partners, if you force yourself to step into the shoes of someone new to your sector who doesn’t get the lingo. Build queries around plain language that would make sense to anyone.
4. Never stop listening to your users.
Robust user testing during the pre-production and post-production phases is critical to ensuring that you keep improving the developer experience. Promote a convenient and publicly-facing feedback engine so that developers can give you useful feedback but also take heart in seeing you be responsive.
5. Keep Iterating
Every mature API program realizes that it can continue to improve. If you aren’t regularly making user-centric improvements to your API, you’re letting it fall behind.
We’ve also assembled an agency checklist that API producers can use as they grow out and mature their efforts. It’s a living document, so feel free to suggest edits! We’re trying to schedule these sessions monthly, going forward. There is still very little out there on the subject of API usability, so we’re documenting everything and will share it with you all shortly.
[Editor’s note: you can also view Gray Brooks’s slides on API Usability Testing from 18F Demo Day on May 9, 2014.]