{
    "version" : "https://jsonfeed.org/version/1",
    "content" : "news",
    "type" : "single",
    "title" : "API Release Kit |Digital.gov",
    "description": "API Release Kit",
    "home_page_url" : "/preview/gsa/digitalgov.gov/bc-archive-content-3/","feed_url" : "/preview/gsa/digitalgov.gov/bc-archive-content-3/2013/05/16/api-release-kit/index.json","item" : [
    {"title" :"API Release Kit","summary" : "These are the elements you should include in your federal API release. Homepage Each of your public APIs needs a page to serve as a hub to provide access to all information and tools associated with it. By using the page’s sidebar, footer, and sub pages, you can directly include or link to each of","date" : "2013-05-16T13:04:03-04:00","date_modified" : "2025-01-27T19:42:55-05:00","authors" : {"gray-brooks" : "Gray Brooks"},"topics" : {
        
            "application-programming-interface" : "Application programming interface",
            "software-engineering" : "Software engineering"
            },"branch" : "bc-archive-content-3",
      "filename" :"2013-05-16-api-release-kit.md",
      
      "filepath" :"news/2013/05/2013-05-16-api-release-kit.md",
      "filepathURL" :"https://github.com/GSA/digitalgov.gov/blob/bc-archive-content-3/content/news/2013/05/2013-05-16-api-release-kit.md",
      "editpathURL" :"https://github.com/GSA/digitalgov.gov/edit/bc-archive-content-3/content/news/2013/05/2013-05-16-api-release-kit.md","slug" : "api-release-kit","url" : "/preview/gsa/digitalgov.gov/bc-archive-content-3/2013/05/16/api-release-kit/","content" :"\u003cdiv class=\"image\"\u003e\n  \u003cimg\n    src=\"https://s3.amazonaws.com/digitalgov/_legacy-img/2014/08/250-x-86-API-letter-blocks-23575697-Hemera-Technologies-PhotoObjects.net-Thinkstock-87667306.jpg\"\n    alt=\"Children\u0026#39;s building blocks letters spelling A P I.\"/\u003e\u003c/div\u003e\n\n\n\u003cp\u003eThese are the elements you should include in your federal API release.\u003c/p\u003e\n\u003ch2 id=\"homepage\"\u003eHomepage\u003c/h2\u003e\n\u003cp\u003eEach of your public APIs needs a page to serve as a hub to provide access to all information and tools associated with it. By using the page’s sidebar, footer, and sub pages, you can directly include or link to each of the following components that exist for the API. This allows for ready discovery of anything a potential developer may need, minimizing the effort that is asked of them and maximizing the adoption. This API homepage should be a webpage, not a downloadable Word or PDF file, in order to provide ease of use as well as a further degree of permanence.\u003c/p\u003e\n\u003cp\u003eYour team should decide which of the following elements to include with your API, recognizing that ensuring a well-rounded and fully functional developer experience is the best recipe for your API’s success. The below list represents elements you should assemble with each API. Examples and suggested tools are included and can be readily copied and improved upon between agencies.\u003c/p\u003e\n\u003ch2 id=\"documentation\"\u003eDocumentation\u003c/h2\u003e\n\u003cp\u003eAPI documentation should include all instructions and details necessary or useful for visiting developers who wish to use the API. Common elements include:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003eDescription of functionality and available information\u003c/li\u003e\n\u003cli\u003eProtocol and format\u003c/li\u003e\n\u003cli\u003eList of end points\u003c/li\u003e\n\u003cli\u003eExample API calls\u003c/li\u003e\n\u003cli\u003eError response codes\u003c/li\u003e\n\u003cli\u003eOther remaining items from this list\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eThis information is often listed in the body of the API homepage and should be generated by the API’s technical producer or by any tools that have been used to generate the API itself. The API’s technical producer should produce the documentation, but by reviewing the documentation of other .gov APIs, you can decide what material is most important for you to also include.\u003c/p\u003e\n\u003ch2 id=\"code-samples\"\u003eCode Samples\u003c/h2\u003e\n\u003cp\u003eBy including sample code snippets that consume the API in the API’s documentation, you provide easy-to-understand case studies for developers to clone, modify, and learn from. Where possible, provide working samples in popular programming languages, such as Javascript, PHP, Ruby, or Python.\u003c/p\u003e\n\u003ch3 id=\"potential-tools\"\u003ePotential Tools\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003eEmbedded \u003ca href=\"https://gist.github.com/\"\u003eGitHub gist\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e html tags\u003c/li\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003c/ul\u003e\n\u003ch3\u003e.Gov Examples\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://developer.dol.gov/\"\u003eDepartment of Labor\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"https://www.federalregister.gov/blog/learn/developers\"\u003eFederal Register\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://developer.nrel.gov/doc/api/georeserv/app/sam/pvwatts#demo-application\"\u003eNational Renewable Energy Laboratory\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://graphical.weather.gov/xml/mdl/XML/Design/WFS_example.php\"\u003eNational Weather Service\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"https://data.energystar.gov/developers/docs/energy-star-certified-clothes-washers\"\u003eEnergyStar.gov\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://healthindicators.gov/Developers/Examples\"\u003eHealthIndicators.gov\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003eInteractive Sample\u003c/h2\u003e\n\u003cp\u003eIn addition to static code examples, you can also provide interactive tools that allow developers to modify the examples and see the change in results. This simple addition supports a quick path towards understanding how the API functions.\u003c/p\u003e\n\u003ch3\u003ePotential Tools\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://swagger.wordnik.com/\"\u003eSwagger\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"https://github.com/mashery/iodocs\"\u003eI/O Docs\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3\u003e.Gov Examples\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"https://www.federalregister.gov/blog/learn/developers\"\u003eFederal Register\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"https://data.energystar.gov/developers/docs/energy-star-certified-clothes-washers\"\u003eEnergyStar.gov\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003eSDKs\u003c/h2\u003e\n\u003cp\u003e\u003ca href=\"http://en.wikipedia.org/wiki/Software_development_kit\"\u003eSoftware Development Kits\u003c/a\u003e (SDKs) are small software libraries that make it easy to employ the associated API with a specific programming language, such as PHP or Ruby. Because many developers have a programming language of choice, you can ensure faster adoption by more developers by offering these in many popular languages. SDKs are often hosted as projects in your agency’s GitHub account, but should also be linked from the API’s homepage.\u003c/p\u003e\n\u003ch3\u003e.Gov Examples\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://developer.dol.gov/\"\u003eDepartment of Labor\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://www.epa.gov/developer/sdk_sample.html\"\u003eEnvironmental Protection Agency\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003eAPI Key Management\u003c/h2\u003e\n\u003cp\u003eIf developers are required to request an API key, the entire experience should be self-service and allow the developer to move forward once the key has been issued. When an agency is publishing multiple APIs that use keys, a developer should be able to use the same key for each API instead of needing to register and keep track of individual ones.\u003c/p\u003e\n\u003ch3\u003ePotential Tools\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://api.data.gov/\"\u003eAPI.Data.gov (beta)\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3\u003e.Gov Examples\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"https://devtools.dol.gov/developer\"\u003eDepartment of Labor\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://www.census.gov/developers/tos/key_request.html\"\u003eCensus Bureau\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://www.ncdc.noaa.gov/cdo-web/token\"\u003eNational Climate Data Center\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://developer.nrel.gov/signup\"\u003eNational Renewable Energy Laboratory\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"https://mobile.fmcsa.dot.gov/developer/home.page\"\u003eFederal Motor Carrier Safety Administration\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"https://data.energystar.gov/developers/docs/energy-star-certified-clothes-washers\"\u003eEnergyStar.gov\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003eIssue Tracker\u003c/h2\u003e\n\u003cp\u003eDevelopers need a clear and transparent means of reporting bugs or other issues that affect the API, and the API producer needs a functional means of managing these items. By doing this, the agency ensures the best customer service and incentivizes API adoption. Issue trackers can be stood up for each API individually, though it is more common to maintain one aggregate tracker to be made available at the developer hub level.\u003c/p\u003e\n\u003cp\u003eFree and open-source tools exist for this function, but possibly the quickest and easiest means is to create a stand-alone repository for the API in the agency’s GitHub account and employ the Issue Tracker functionality to receive and process developer feedback. In addition to being free, scalable, and requiring no infrastructure, this choice also has the added benefit of existing within the GitHub ecosystem, which is the norm within the developer community. This option also allows agency staff or other developers to subscribe to updates and receive alerts.\u003c/p\u003e\n\u003ch3\u003ePotential Tools\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://apievangelist.com/2012/09/23/api-issue-management-with-github/\"\u003eGitHub Issue Tracker\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3\u003e.Gov Examples\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"https://github.com/USDepartmentofLabor/DOLAPI/issues\"\u003eDepartment of Labor\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003eContact Info\u003c/h2\u003e\n\u003cp\u003eDevelopers need to have the ability to contact agency staff directly, so it\u0026#8217;s important to offer contact information for an API point of contact. This is often done in agencies by creating an email account at \u003ca href=\"mailto:developer@agency.gov\"\u003edeveloper@agency.gov\u003c/a\u003e and forwarding it to one or several staff who work to field the incoming messages. This would allow the same contact information to be published at the developer hub instead of requiring a unique point of contact to be listed for each API.\u003c/p\u003e\n\u003ch3\u003e.Gov Examples\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://developer.dol.gov/contactfollow-us\"\u003eDepartment of Labor\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://energy.gov/developer-resources\"\u003eDepartment of Energy\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://broadbandmap.gov/developer\"\u003eNational Broadband Map\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://developer.nrel.gov/community\"\u003eNational Renewable Energy Laboratory\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://www.pacer.gov/cmecf/developer/\"\u003eU.S. Courts\u003c/a\u003e\u003ca href=\"http://www.pacer.gov/cmecf/developer/\"\u003e—\u003c/a\u003e\u003ca href=\"http://www.pacer.gov/cmecf/developer/\"\u003ePACER\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003eAPI Roadmap\u003c/h2\u003e\n\u003cp\u003eAny API will be more successful the more that its producers communicate with potential developers and inform them of the near- and long-term plans for the service. One easy means of doing this is to articulate these plans via milestones. This can be done in many ways, but one convenient and productive method is to employ the milestones functionality of GitHub in the same fashion as with Issue Tracking (it is actually integrated within the Issues section of any repository, alongside the issue tracker, but can be used in parallel). This allows agency staff or other developers to subscribe to updates and receive alerts.\u003c/p\u003e\n\u003ch3\u003ePotential Tools\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://apievangelist.com/2012/11/12/communicate-your-api-roadmap-with-github/\"\u003eGitHub Milestones\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3\u003e.Gov Examples\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://www.epa.gov/developer/ef_api.html#future\"\u003eEnvironmental Protection Agency\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003eChangelog\u003c/h2\u003e\n\u003cp\u003eOver time, your API design may change and the documentation updated. Providing a changelog allows your developers to see at a glance what has changed and to better understand what impact the changes may have on their use of your API. This can be done through API version control, with each update receiving a version number and including a bulleted list of changes. It\u0026#8217;s also helpful to provide clear track changes to the API documentation, a task that is automatically integrated into any documentation you publish through GitHub. By posting the full text in GitHub, all future edits will clearly reflect changes so your developers can see at a glance what they need to know.\u003c/p\u003e\n\u003ch3\u003ePotential Tools\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://apievangelist.com/2012/10/24/version-control-your-api-documentation-with-github/\"\u003eGitHub\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3\u003e.Gov Examples\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://graphical.weather.gov/xml/#xml_changes\"\u003eNational Weather Service\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://www.aesdirect.gov/support/weblink_api_updates.html\"\u003eCommerce—Automated Export System\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://healthindicators.gov/Developers/ReleaseNotes\"\u003eHealthIndicators.gov\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003eFAQ\u003c/h2\u003e\n\u003cp\u003eAny common developer questions may reflect confusion held by other potential users. Maintaining a short list of frequently asked questions and answers provides a simple utility today as well as a good catch-all for future disclaimers and loose information that may come to mind in the future.\u003c/p\u003e\n\u003ch3\u003e.Gov Examples\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://developer.dol.gov/frequently-asked-questions\"\u003eDepartment of Labor\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://www.drugabuse.gov/developers/nmassist/faq\"\u003eNational Institute on Drug Abuse\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://graphical.weather.gov/xml/\"\u003eNational Weather Service\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003eWidgets\u003c/h2\u003e\n\u003cp\u003eA particularly advanced way to drive adoption of your API is to also offer embeddable \u003ca href=\"http://en.wikipedia.org/wiki/Web_widget\"\u003ewidgets\u003c/a\u003e that consume the API for use by developers and non-experts alike. Many sources of data are clear candidates for widgets that offer the most recent or popular items from the material. APIs allow advanced integration of this data, but by offering simple widgets that non-experts can use for common implementations, the faster, easier turnaround for third-parties will drive interest and adoption at all levels.\u003c/p\u003e\n\u003ch3\u003e.Gov Examples\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"http://my.fcc.gov/dashboard\"\u003eFederal Communications Commission\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"http://aidsinfo.nih.gov/widgets\"\u003eAIDSinfo\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n"}
  ]
}