{
    "version" : "https://jsonfeed.org/version/1",
    "content" : "news",
    "type" : "single",
    "title" : "API Basics |Digital.gov",
    "description": "API Basics",
    "home_page_url" : "/preview/gsa/digitalgov.gov/cm-topics-button-component/","feed_url" : "/preview/gsa/digitalgov.gov/cm-topics-button-component/2013/03/12/api-basics/index.json","item" : [
    {"title" :"API Basics","summary" : "Common Technical Choices Protocol API protocol is the set of rules that govern how an API functions. The protocol outlines the structure and definitions of the API. The two common forms are REST and SOAP. REST is the dominant choice for API protocol because it uses the http protocol that powers the Web. REST supports more","date" : "2013-03-12T12:24:59-04:00","date_modified" : "2024-04-02T09:45:13-04:00","authors" : {"gray-brooks" : "Gray Brooks"},"topics" : {
        
            "application-programming-interface" : "Application programming interface",
            "software-engineering" : "Software Engineering"
            },"branch" : "cm-topics-button-component",
      "filename" :"2013-03-12-api-basics.md",
      
      "filepath" :"news/2013/03/2013-03-12-api-basics.md",
      "filepathURL" :"https://github.com/GSA/digitalgov.gov/blob/cm-topics-button-component/content/news/2013/03/2013-03-12-api-basics.md",
      "editpathURL" :"https://github.com/GSA/digitalgov.gov/edit/cm-topics-button-component/content/news/2013/03/2013-03-12-api-basics.md","slug" : "api-basics","url" : "/preview/gsa/digitalgov.gov/cm-topics-button-component/2013/03/12/api-basics/","content" :"\u003ch2 id=\"common-technical-choices-hahahugoshortcode1591s0hbhb\"\u003eCommon Technical Choices \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\u003c/h2\u003e\n\u003ch3 id=\"protocol\"\u003eProtocol\u003c/h3\u003e\n\u003cp\u003eAPI protocol is the set of rules that govern how an API functions. The protocol outlines the structure and definitions of the API. The two common forms are REST and SOAP.\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"http://en.wikipedia.org/wiki/Representational_state_transfer\"\u003eREST\u003c/a\u003e is the dominant choice for API protocol because it uses the http protocol that powers the Web. REST supports more data formats, requires much simpler documentation, has better performance, can be cached, and is faster to use. REST uses universal commands such as GET (to retrieve information), POST (to submit information), PUT (to update information), and DELETE (to delete information) to provide the logic that powers the API.\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"http://en.wikipedia.org/wiki/SOAP\"\u003eSOAP\u003c/a\u003e has its own protocol and logic. SOAP may be a good choice for some applications that may require transaction confirmation. With SOAP, the structure and definitions are decided by the API creator and may vary widely.\u003c/p\u003e\n\u003ch3 id=\"format__api-formats-are-the-schema-that-developers-use-to-interact-with-an-api8217s-protocol-xmlhttpenwikipediaorgwikixml-and-jsonhttpenwikipediaorgwikijson-are-the-most-common-choices-each-has-different-benefits\"\u003eFormat_​_API formats are the schema that developers use to interact with an API’s protocol. \u003ca href=\"http://en.wikipedia.org/wiki/XML\"\u003eXML\u003c/a\u003e and \u003ca href=\"http://en.wikipedia.org/wiki/JSON\"\u003eJSON\u003c/a\u003e are the most common choices; each has different benefits.\u003c/h3\u003e\n\u003cp\u003eXML can be more human-readable and may offer better structure in some circumstances. JSON is usually lighter, faster, more functional than XML, and better integrated into modern code languages.\u003c/p\u003e\n\u003cp\u003eMany APIs offer both as choices for developers, which may not add much additional work. If your agency can only make one format available, JSON is likely the more productive choice.\u003c/p\u003e\n\u003ch3 id=\"endpoints\"\u003eEndpoints\u003c/h3\u003e\n\u003cp\u003eAn API’s endpoint is the basic entry point to a Web service, oftentimes a URL that can be customized to accept different queries. Many organizations begin by creating individual APIs for each data set or service. Over time, best practices and efficiency promote consolidation to a single API endpoint that offers different material depending on which set is queried.\u003c/p\u003e\n\u003cp\u003eThe advantage to a single API endpoint is that developers can build applications more easily because they do not need to learn how to use multiple APIs. If your agency is just beginning its API efforts, starting with one consolidated API that you build out instead of creating a new API for each service avoids the work of consolidating APIs in the future.\u003c/p\u003e\n\u003ch3 id=\"api-keys__api-keys-are-an-optional-functionality-that-some-producers-use-to-control-access-to-their-api-identify-who-is-consuming-the-api-and-gather-analytics-from-the-api-api-key-management-can-be-maintained-through-lightweight-open-source-methods-that-allow-users-to-register-and-acquire-one-automatically-the-api-producer-can-then-monitor-and-manage-api-usage-rates-if-a-user-violates-the-apis-terms-of-service-it-is-possible-to-then-block-their-api-key\"\u003eAPI Keys_​_API keys are an optional functionality that some producers use to control access to their API, identify who is consuming the API, and gather analytics from the API. API key management can be maintained through lightweight, open source methods that allow users to register and acquire one automatically. The API producer can then monitor and manage API usage rates. If a user violates the API’s Terms of Service, it is possible to then block their API key.\u003c/h3\u003e\n\u003cp\u003eRequiring API keys can be a barrier to developers accessing and using your API. Agencies need to balance the management advantages against adoption concerns when deciding whether or not to require keys.\u003c/p\u003e\n\u003ch3 id=\"analytics__it-is-very-important-to-understand-how-an-api-is-being-used-analytics-can-be-derived-through-one-of-several-methodsan-api-key-server-logs-or-through-the-use-of-api-management-service-providers-analytics-can-help-identify-problems-that-developers-may-be-experiencing-as-well-as-solutions-to-make-their-user-experience-better-learn-more-about-api-analyticshttpsdigitalgov20130312api-analytics-api-analytics\"\u003eAnalytics_​_It is very important to understand how an API is being used. Analytics can be derived through one of several methods—an API key, server logs, or through the use of API management service providers. Analytics can help identify problems that developers may be experiencing as well as solutions to make their user experience better. Learn more about \u003ca href=\"https://digital.gov/2013/03/12/api-analytics/\" title=\"API Analytics\"\u003eAPI analytics\u003c/a\u003e.\u003c/h3\u003e\n\u003ch3 id=\"documentation__api-documentationhttpsdigitalgov20130312api-design-and-documentation-api-design-and-documentation-is-the-pages-that-explain-how-an-api-works-and-conveys-any-other-information-tools-or-resources-that-may-be-of-use-to-a-prospective-developer-learn-more-about-api-design-and-documentationhttpsdigitalgov20130312api-design-and-documentation-api-design-and-documentation\"\u003eDocumentation_​_API \u003ca href=\"https://digital.gov/2013/03/12/api-design-and-documentation/\" title=\"API Design and Documentation\"\u003edocumentation\u003c/a\u003e is the page(s) that explain how an API works and conveys any other information, tools, or resources that may be of use to a prospective developer. Learn more about \u003ca href=\"https://digital.gov/2013/03/12/api-design-and-documentation/\" title=\"API Design and Documentation\"\u003eAPI design and documentation\u003c/a\u003e.\u003c/h3\u003e\n\u003ch2 style=\"text-align: center\"\u003e\n  Common Practical Issues\n\u003c/h2\u003e\n\u003ch3 id=\"security__just-like-a-new-section-of-a-website-so-should-a-new-api-receive-a-security-scan-from-an-agencys-it-security-team-oftentimes-especially-with-restful-apis-they-can-use-the-same-tools-to-scan-for-vulnerabilities-when-the-api-is-read-only-the-review-is-often-much-simpler-but-the-technology-to-secure-and-support-read-write-apis-is-very-mature-and-readily-available-for-information-and-services-with-which-the-public-already-interacts-there-shouldnt-be-any-compelling-security-reason-that-prevents-api-generation-similarly-for-internal-only-apis-the-methods-of-ensuring-that-they-stay-protected-within-the-network-are-well-documented-learn-more-about-api-securityhttpsdigitalgov20130729api-security-api-security\"\u003eSecurity_​_Just like a new section of a website, so should a new API receive a security scan from an agency’s IT Security team. Oftentimes, especially with RESTful APIs, they can use the same tools to scan for vulnerabilities. When the API is read-only, the review is often much simpler, but the technology to secure and support read-write APIs is very mature and readily available. For information and services with which the public already interacts, there shouldn’t be any compelling security reason that prevents API generation. Similarly, for internal-only APIs, the methods of ensuring that they stay protected within the network are well-documented. Learn more about \u003ca href=\"https://digital.gov/2013/07/29/api-security/\" title=\"API Security\"\u003eAPI security\u003c/a\u003e.\u003c/h3\u003e\n\u003ch3 id=\"legal__an-api8217s-terms-of-service-exists-to-express-any-guidance-or-restriction-for-the-api-and-to-address-any-open-legal-issues-such-as-attribution-modification-false-representation-right-to-limit-right-to-terminate-and-indemnification-many-of-these-issues-may-already-be-represented-on-the-agencys-page-for-website-policies-but-any-questions-should-be-discussed-with-the-agencys-general-counsel-this-is-a-particularly-good-area-to-review-the-terms-of-service-of-other-government-apis-and-consider-re-using-their-material-instead-of-starting-from-scratch\"\u003eLegal_​_An API’s terms of service exists to express any guidance or restriction for the API and to address any open legal issues such as attribution, modification, false representation, right to limit, right to terminate, and indemnification. Many of these issues may already be represented on the agency’s page for website policies, but any questions should be discussed with the agency’s general counsel. This is a particularly good area to review the terms of service of other government APIs and consider re-using their material instead of starting from scratch.\u003c/h3\u003e\n"}
  ]
}