{
    "version" : "https://jsonfeed.org/version/1",
    "content" : "news",
    "type" : "single",
    "title" : "Usability Testing + Gov APIs = Best |Digital.gov",
    "description": "Usability Testing + Gov APIs = Best",
    "home_page_url" : "/preview/gsa/digitalgov.gov/bc-archive-content-3/","feed_url" : "/preview/gsa/digitalgov.gov/bc-archive-content-3/2013/04/29/usability-testing-gov-apis-best/index.json","item" : [
    {"title" :"Usability Testing + Gov APIs = Best","summary" : "Good APIs can transform intimidating data sets into something that people can use. Good government APIs can create a better connection between government and citizens. The Digital Government Strategy has spurred Federal adoption of APIs, and the Digital Services Innovation Center and DATA.GOV teams are supporting these efforts by releasing a swath of guidance and","date" : "2013-04-29T04:37:18-04:00","date_modified" : "2025-01-27T19:42:55-05:00","authors" : {"gray-brooks" : "Gray Brooks"},"topics" : {
        
            "application-programming-interface" : "Application programming interface",
            "research" : "Research"
            },"branch" : "bc-archive-content-3",
      "filename" :"2013-04-29-usability-testing-gov-apis-best.md",
      
      "filepath" :"news/2013/04/2013-04-29-usability-testing-gov-apis-best.md",
      "filepathURL" :"https://github.com/GSA/digitalgov.gov/blob/bc-archive-content-3/content/news/2013/04/2013-04-29-usability-testing-gov-apis-best.md",
      "editpathURL" :"https://github.com/GSA/digitalgov.gov/edit/bc-archive-content-3/content/news/2013/04/2013-04-29-usability-testing-gov-apis-best.md","slug" : "usability-testing-gov-apis-best","url" : "/preview/gsa/digitalgov.gov/bc-archive-content-3/2013/04/29/usability-testing-gov-apis-best/","content" :"\u003cp\u003eGood APIs can transform intimidating data sets into something that people can use. Good government APIs can create a better connection between government and citizens. The \u003ca href=\"http://www.whitehouse.gov/sites/default/files/omb/egov/digital-government/digital-government.html\"\u003eDigital Government Strategy\u003c/a\u003e has spurred Federal adoption of APIs, and the Digital Services Innovation Center and DATA.GOV teams are supporting these efforts by releasing a \u003ca href=\"http://www.howto.gov/mobile/apis-in-government\" title=\"api resources\"\u003eswath of guidance and resources\u003c/a\u003e, \u003ca href=\"http://www.howto.gov/training/on-demand#apis-and-data\" title=\"api webinars\"\u003ehosting online education series\u003c/a\u003e and launching a number of hosted tools at \u003ca href=\"http://labs.data.gov/\" title=\"labs.data.gov\"\u003eLabs.Data.gov\u003c/a\u003e.\u003c/p\u003e\n\u003cp\u003eAlways looking to build off other successful programs, we looked to GSA’s \u003ca href=\"http://www.howto.gov/web-content/usability/first-fridays\" title=\"first fridays program\"\u003eFirst Fridays usability testing program\u003c/a\u003e. That team regularly hosts half-day sessions to provide actionable usability feedback for websites. We wanted to see how that model could assist agencies make their APIs programs better–and more usable.\u003c/p\u003e\n\u003cp\u003eSeven energetic API teams – the \u003ca href=\"http://www.broadbandmap.gov/developer\" title=\"fcc apis\"\u003eFederal Communications Commission\u003c/a\u003e, \u003ca href=\"http://www.eia.gov/developer/\" title=\"EIA developer page\"\u003eEnergy Information Administration\u003c/a\u003e, \u003ca href=\"http://search.digitalgov.gov/developer/\" title=\"usasearch api\"\u003eGeneral Services Administration\u003c/a\u003e, \u003ca href=\"http://www.ers.usda.gov/developer.aspx\" title=\"ERS developer hub\"\u003eEconomic Research Service\u003c/a\u003e, \u003ca href=\"http://pillbox.nlm.nih.gov/developer.html\" title=\"NIH API\"\u003eNational Institutes of Health\u003c/a\u003e, \u003ca href=\"http://www.census.gov/developers\"\u003eCensus Bureau\u003c/a\u003e, and \u003ca href=\"http://www.usa.gov/About/developer-resources/developers.shtml\" title=\"USA.gov developer hub\"\u003eUSA.gov\u003c/a\u003e – signed up to spend a morning with our pilot API usability evaluations.\u003c/p\u003e\n\u003cp\u003eWe found equally energetic volunteer developer testers to run through the agencies’ developer portals, API documentation, and even the actual API endpoints – taking on the role of a citizen developer looking at this material for the first time. By sharing aloud their thoughts and reactions at each stage, these fresh perspectives from experienced developers offered tremendous value.\u003c/p\u003e\n\u003cp\u003eWhile the agency API program teams received plenty of feedback to build on, a number of consistent developer needs stood out as practices that all agencies with developer portals need to address. Here are a few.\u003c/p\u003e\n\u003ch3 id=\"api-usability-good-practices\"\u003eAPI Usability Good Practices\u003c/h3\u003e\n\u003ch4 id=\"make-a-hub\"\u003eMake a Hub\u003c/h4\u003e\n\u003cul\u003e\n\u003cli\u003eCreate a central developer hub with a path to each of your APIs and all related resources.\u003c/li\u003e\n\u003cli\u003eMake your hub findable by using a common URL: \u003ca href=\"https://www.agency.gov/developer\"\u003ewww.agency.gov/developer\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003eEvery API in your central hub should have a homepage with links to all of its related resources.\u003c/li\u003e\n\u003cli\u003eOffer clear and user friendly navigation throughout the developer hub.\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch4 id=\"provide-good-documentation\"\u003eProvide good documentation\u003c/h4\u003e\n\u003cul\u003e\n\u003cli\u003eAPI documentation should be in web pages, not a PDF or a Word Document.\u003c/li\u003e\n\u003cli\u003eProvide interactive documentation such as Swagger or I/O Docs.\u003c/li\u003e\n\u003cli\u003eProvide consistent layout, structure, design, and resources for each set of API documentation.\u003c/li\u003e\n\u003cli\u003eHighlight the API endpoint and example URLs early so that developers can jump right in!\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch4 id=\"communicate-with-your-developers\"\u003eCommunicate with your developers\u003c/h4\u003e\n\u003cul\u003e\n\u003cli\u003ePlain language helps everyone – beginners and experts. Ask yourself: Would someone who is new to our agency’s work understand this?\u003c/li\u003e\n\u003cli\u003eGive people an overview: what the data is, what you can do with it, how to get started\u003c/li\u003e\n\u003cli\u003eAvoid acronyms.\u003c/li\u003e\n\u003cli\u003eIf you require API keys in order to interact with the end point, be sure to allow instant registration. If developers have to wait–even minutes–before they can interact with the data, they will go elsewhere.\u003c/li\u003e\n\u003cli\u003eProvide a means for developers to sign up for updates or see the latest news for these APIs.\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch4 id=\"dont-just-tell-them-show-them\"\u003eDon’t just tell them, show them\u003c/h4\u003e\n\u003cul\u003e\n\u003cli\u003eInclude plenty of examples (and go ahead and hyperlink them for convenience). Offer code samples and examples of applications that consume the API.\u003c/li\u003e\n\u003cli\u003eShare code samples, SDKs, and other developer resources through your agency’s GitHub account.\u003c/li\u003e\n\u003cli\u003eInclude JSON support. Offering JSONP support also goes a long way to encouraging re-use on third party websites.\u003c/li\u003e\n\u003cli\u003eIf API returns are lengthy, offer pagination.\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eOne prime example of government adopting developer norms is the recent \u003ca href=\"https://github.com/WhiteHouse/api-standards\" title=\"white house api standards\"\u003eAPI Standards\u003c/a\u003e released by the White House. Check it out and we will spend more time on that later!\u003c/p\u003e\n"}
  ]
}