{
    "version" : "https://jsonfeed.org/version/1",
    "content" : "news",
    "type" : "single",
    "title" : "Why Your APIs Need Design Help |Digital.gov",
    "description": "Why Your APIs Need Design Help",
    "home_page_url" : "/preview/gsa/digitalgov.gov/bc-archive-content-3/","feed_url" : "/preview/gsa/digitalgov.gov/bc-archive-content-3/2015/03/16/why-your-apis-need-design-help/index.json","item" : [
    {"title" :"Why Your APIs Need Design Help","summary" : "Anything built should be built right. It doesn’t matter if it’s built of wood, carbon nanotubes or code. So it’s encouraging that the practice of User-Centered Design—getting customer feedback at every stage of a project—is catching on with","date" : "2015-03-16T10:00:28-04:00","date_modified" : "2025-01-27T19:42:55-05:00","authors" : {"jonathan-rubin" : "Jonathan Rubin"},"topics" : {
        
            "application-programming-interface" : "Application programming interface",
            "human-centered-design" : "Human-centered design",
            "software-engineering" : "Software engineering",
            "usability" : "Usability",
            "user-experience" : "User experience"
            },"branch" : "bc-archive-content-3",
      "filename" :"2015-03-16-why-your-apis-need-design-help.md",
      
      "filepath" :"news/2015/03/2015-03-16-why-your-apis-need-design-help.md",
      "filepathURL" :"https://github.com/GSA/digitalgov.gov/blob/bc-archive-content-3/content/news/2015/03/2015-03-16-why-your-apis-need-design-help.md",
      "editpathURL" :"https://github.com/GSA/digitalgov.gov/edit/bc-archive-content-3/content/news/2015/03/2015-03-16-why-your-apis-need-design-help.md","slug" : "why-your-apis-need-design-help","url" : "/preview/gsa/digitalgov.gov/bc-archive-content-3/2015/03/16/why-your-apis-need-design-help/","content" :"\u003cdiv class=\"image\"\u003e\n  \u003cimg\n    src=\"https://s3.amazonaws.com/digitalgov/_legacy-img/2015/02/600-x-258-This-is-the-openFDA-API-endpoint-for-adverse-drug-event-reports-since-2004.jpg\"\n    alt=\"This is the openFDA API endpoint for adverse drug event reports since 2004\"/\u003e\u003c/div\u003e\n\n\n\u003cp\u003eAnything built should be built right. It doesn’t matter if it’s built of wood, carbon nanotubes or code. So it’s encouraging that the practice of User-Centered Design—getting customer feedback at every stage of a project—is catching on with APIs as well.\u003c/p\u003e\n\u003cp\u003eWhen we think APIs, we mostly think of developers and not designers. But the experience of those who want to use your APIs isn’t just dependant of the strength and elegance of your API. The first thing they see, after all, isn’t your magnificent code but your documentation page. If people can’t quickly understand the value of your API, and can’t effortless try it out, they’ll bail. And then all your blood, sweat and tears go down the drain.\u003c/p\u003e\n\u003cp\u003eFor the past two years, our \u003ca href=\"http://18f.github.io/API-Usability-Testing/\"\u003eAPI Usability Evaluation program\u003c/a\u003e has connected federal API teams with unbiased, no-holds barred feedback from expert developers. We’ve introduced dozens of gov teams to the concept of usability, of designing something that’s intuitive, transparent, credible and, ultimately, useful. Often, the feedback included some of the same design suggestions. We would consistently hear:\u003c/p\u003e\n\u003ch4 id=\"1-use-json\"\u003e1. Use JSON\u003c/h4\u003e\n\u003cp\u003eMany government APIs still return API calls in XML. This is usually considered old school at best, or annoying or frustrating at worst. Go with the trends, and deliver what people expect. As one evaluator said, “If I’m not getting JSON, I’m turned off.”\u003c/p\u003e\n\u003ch4 id=\"2-communicate-value-immediately\"\u003e2. Communicate value immediately\u003c/h4\u003e\n\u003cp\u003eSince we don’t always know what people are doing with our data, or what their backgrounds are, we need to assume they aren’t familiar with us, our data or our mission. The \u003ca href=\"http://cfpb.github.io/api/hmda/\"\u003eConsumer Financial Protection Bureau’s API\u003c/a\u003e puts it up front and center: Here’s who we are and what you can use this for. It’s also good to include success stories or use cases of people using your product. Bonus points: Link to things they’ve created!\u003c/p\u003e\n\u003ch4 id=\"3-allow-easy-access\"\u003e3. Allow easy access\u003c/h4\u003e\n\u003cp\u003eIf you require an API key, say so and why. Test it out and see if you’re providing a good experience, but no matter what make it easy and automated. Developers will give up and move on if key registration isn’t immediate.\u003c/p\u003e\n\u003ch4 id=\"4-do-as-developers-do\"\u003e4. Do as developers do\u003c/h4\u003e\n\u003cp\u003eOnce again, use the tools and conventions that people are expecting and familiar with. Posting your API info in GitHub, according to one tester, “gives me confidence that you’re using the language of the developers.” Also, use RESTful APIs and allow bulk download of datasets.\u003c/p\u003e\n\u003ch4 id=\"5-offer-sample-code\"\u003e5. Offer sample code\u003c/h4\u003e\n\u003cp\u003eLet people test drive the car before investing in it. Providing interactive documentation where they can test the code gives them that ability, and shows that you are confident in your API. A nice example of this is the \u003ca href=\"https://open.fda.gov/\"\u003eOpenFDA API\u003c/a\u003e, and here’s a \u003ca href=\"/preview/gsa/digitalgov.gov/bc-archive-content-3/2014/08/22/api-usability-case-study-openfda/\"\u003eusability case study\u003c/a\u003e that goes into detail why we like this one so much.\u003c/p\u003e\n\u003ch4 id=\"6-pay-attention-to-details\"\u003e6. Pay attention to details\u003c/h4\u003e\n\u003cp\u003eFinally, anything that seems off about your API will make people think it’s not reliable, or that it might not work. You want people to have confidence in your API, so they’ll feel it’s worth their time to dive in. So make sure all your links work, that there’s no spelling mistakes or bad paragraph breaks, and that it looks like you know what you’re doing.\u003c/p\u003e\n"}
  ]
}