Common Technical Choices
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 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.
SOAP 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.
Format__API formats are the schema that developers use to interact with an API’s protocol. XML and JSON are the most common choices; each has different benefits.
XML 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.
Many 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.
An 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.
The 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.
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 API’s Terms of Service, it is possible to then block their API key.
Requiring 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.