APIs are the “glue” that connects different pieces of software. Any change to an API call can force another business to change its software unexpectedly, or even drive those users to find another API option. API planning must carefully account for potential impacts to API users and user satisfaction.
API management should address key business issues, including the following:
Just as businesses apply software lifecycle management techniques to enterprise platforms, businesses apply virtually identical API lifecycle management practices to guide APIs from planning through deprecation. An API lifecycle strategy typically involves five broad stages:
As with all software, APIs are iterative, and these lifecycle steps may repeat countless times throughout the life of any API. API development and testing may repeat many times before a single version is accepted for release.
APIs have two acute requirements that other software products may lack: backward compatibility and strong documentation. Both of these factors should figure prominently in an API strategy and lifecycle.
Similarly, APIs require copious documentation that details the parameters and arguments of every call. It should provide clear examples for each call, as well as numerous calls in context — for instance, sample software code that employs the API. Other developers must have a clear reference and guide to help write software that can effectively use the API.
Security. APIs expose business data and workloads to other applications, including web browsers. Consequently, APIs are a sensitive attack surface for malicious activity, such as data theft. Developers must emphasize API security and adopt sophisticated methodologies that include the following:
How to solve this challenge: Create API security guidelines to stipulate the minimum requirements and preferences for API authentication and authorization. For example, use OAuth or MFA along with encryption such as Secure Sockets Layer (SSL) or TLS; implement least-privilege access; and set requirements for graceful error handling and access reporting/logging.
Testing. Nothing disenfranchises users faster than an API that produces errors or fails to operate as promised. It’s vital to thoroughly test APIs to ensure that every version will perform properly. API testing should be performed frequently, or even continuously, and in short cycles. API testing should take place after any significant code change, and run after any database changes to verify the database functions with the application as expected.
How to solve this challenge: Codify API testing practices to ensure that APIs follow similar rigorous testing and comprehensive test case creation. For example, stipulate the use of API testing tools; the types of tests that should be employed, such as security, smoke or canary testing; the test cases that should be used, such as common test databases; and determine a location for test results and test result retention
Version control. To manage requests and responses between multiple computer and software systems, APIs must be completely predictable. Every system must know precisely how the API interface operates, along with all of the available calls, arguments, parameters, messages and so on. API software changes affect all of these items, which can interrupt or corrupt data access and flow, and force API users to adjust their systems — a source of dissatisfaction.
How to solve this challenge: A clearly defined API versioning strategy and careful version control give users backward compatibility and ample time to make necessary changes to accommodate new calls and features in the latest API version.
Documentation. APIs are particularly dependent on documentation to outline the available calls, arguments, parameters, messages and other elements associated with an API. Documentation must be clear and precise, offering examples and explanations that help developers adopt and integrate the API.
Documentation is closely associated with version control. Changes to an aspect of the API, or a new API version release, can alter how that API interacts with other systems and can lead to errors or failures if these changes are not properly documented.
How to solve this challenge: Proper API documentation allows users to test and adopt an API quickly and completely with a minimum of errors and frustration. Typical API documentation guidelines include reference data focusing on API calls and syntax, examples showing how API calls are used, and tutorials that offer broader examples in context and offer access to API developer support or additional information.
API gateway. The API gateway is the focal point for API messaging. It receives API calls, moves them to the appropriate API, receives the response and forwards it to the calling software. With an API gateway, a business can see and control a broad scope of APIs and integrations centrally, rather than attempt to track and manage APIs individually within the environment. API gateways typically include monitoring and logging capabilities to record and analyze calls and responses in order to ensure security and evaluate errors.
An alternative to the API gateway is an API proxy, which is basically a subset or specialized version of an API gateway that provides minimal processing for API requests. The API proxy handles communication, including protocol translation, between specific software platforms, such as a proxy endpoint and target API. It can also control the flow of traffic between sending and receiving points.
API documentation engine. API management tools increasingly utilize documentation engines to automate common tasks, such as reference data focusing on API calls and syntax, examples showing how API calls are used and tutorials that offer broader examples in context. This ensures accuracy, timeliness and consistency, especially in enterprises where multiple developers work on APIs.
There are numerous API management platforms available today, including Apigee (owned by Google), Akana, Azure API Management, MuleSoft Anypoint Platform, Postman, Tibco Cloud Mashery, Workato and others. Public cloud providers offer API tools to connect services and data on their respective platforms, such as Amazon API Gateway, Google Cloud Endpoints and Microsoft Azure API Management.
Organizations also can obtain and use certain standalone API management components, such as API gateway tools. Examples include Oracle API Gateway, Kong Gateway, cloud platform-specific options include Amazon API Gateway and Azure API Gateway.
