Guide to building an enterprise API strategy

How do APIs benefit businesses?

As businesses increasingly depend on software-based services to generate revenue, the creation and maintenance of APIs has become a major part of business strategy. A rich and diverse API ecosystem enables a business to access, process and provide data, then derive revenue from those activities either directly through sales or indirectly through better efficiency; this is called the API economy. APIs can be created, updated and used more quickly than physical products.

Businesses can employ a range of API types to achieve the desired interface. Open APIs are typically unrestricted and publicly available to any developer, business or user. Partner APIs are intended for use by external business partners or specifically authorized organizations. Internal APIs are private interfaces that communicate and collaborate between an organization's internal systems. Composite APIs aggregate multiple API calls into one response to boost processing and performance of related tasks.

API developers can also work with four common types of web service APIs:

• Simple Object Access Protocol (SOAP) APIs exchange data in XML format and are most often used for messaging and communication.
• XML-RPC uses a specific and proprietary XML format that is simpler than SOAP-based APIs.
• JSON-RPC is a protocol similar to XML-RPC but uses a JSON format to transfer data.
• REST (representational state transfer) provides a set of architectures and principles that use HTTP requests to access and use data, including PUT, GET, POST and DELETE.

The popularity of APIs and the range of types and protocols available to developers enable organizations to rapidly develop and deploy diverse combinations to suit specific business purposes or user groups without the need to re-architect software. Organizations of any size or experience with software development can build and enhance the business in ways that would be impossible with traditional proprietary software development.

Ultimately, APIs bring several important benefits to the business:

B2B collaboration. Businesses create software to solve business problems or perform business tasks. The solution may exist with external software and data. APIs allow one business to share in the software and data offered by another business. Cloud providers, such as AWS, offer API gateways that allow developers to build and offer secure APIs.

Customer experience. An API's interoperability and ability to add value translates into a superior user experience, customer satisfaction and support. For example, a transportation company uses an API from a map data company to display routes to drivers, with another API to overlay road and traffic hazard alerts to drivers and yet another API to overlay weather conditions. This combination makes drivers safer, more efficient and more productive. As another example, healthcare provider software employs APIs that federate patient data from multiple providers, which presents physicians with fuller patient histories.

Product and service innovation. Faster pace of business leaves little room for missteps or failed projects. Many organizations cannot develop or deliver traditional proprietary software. APIs allow even small businesses to operate within the same playing field as larger enterprises. APIs are smaller and easier to update or modify than fully developed applications, which allows API providers to respond quickly to changing customer needs or new business opportunities with new or enhanced API offerings.

On-ramp to the public cloud. Businesses exploring cloud adoption quickly realize that cloud development APIs are essential to the creation and delivery of services through the web. APIs handle every login, provisioned resource and data exchange between a public cloud and cloud user. Businesses can select a provider-specific API such as the Microsoft Azure REST API, or cross-platform APIs such as Apache's jclouds and Libcloud.

What are the use cases for APIs in the enterprise?

APIs expose data and support interactions with the enterprise and requesters. Private APIs created and deployed within the enterprise allow interaction between two or more in-house software platforms. Public APIs, created and deployed to support outside or third-party interactions, allow other software such as user endpoints to utilize enterprise data and services.

An enterprise might develop, maintain and use dozens or even hundreds of public and private APIs. The generic nature of APIs makes them indispensable across a vast range of use cases; some businesses, such as those in retail, financial services, transportation and healthcare, use industry-specific APIs.

Why is having an API strategy important?

The larger role of APIs in the enterprise requires businesses to intelligently plan their API development and management efforts. It's not enough to simply create and release an API -- or adopt an outside API -- and hope for the best. Comprehensive API management helps address the needs of developers, applications, users and the business in a cohesive manner.

A formal, detailed API management strategy defines desired API features and roadmaps, and codifies and outlines key elements of API design, security and documentation. With these, a business can standardize its APIs, share components and development personnel, meet desired quality and performance standards, and boost security and regulatory compliance requirements.

API management should address key business issues, including the following:

• Does the API provide the features and functionality that applications and users need?
• How does the business control the API's release and future development?
• Does the API provide enough authorization and authentication to guard business data and workloads from unauthorized access or alteration? Is API security adequately tested during development?
• How is the API being used? How many API calls is the business handling month over month? What tools are available and deployed to monitor API utilization and performance?
• Does the API support the business strategy? Does the API support the organization's regulatory compliance requirements? Is the API's utilization logged and audited?

API lifecycle management

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:

1. API design. In this planning phase, an organization discusses its technical and business needs, formalizes the fundamental requirements for the API, and approves design specifications and documentation. Common API design best practices include outlining preferences in API language, naming standards, layout, messaging and architecture.
2. API development. Developers code the API using everyday development tools and common programming languages, such as PHP, Python, Ruby, Visual C# .NET, Java, Perl and others.
3. API testing. The organization thoroughly tests the API build's functionality, performance and security. Testing is an important phase for enterprise software, and it demands careful attention from qualified software testers.
4. API deployment. Once a version of the API is approved for deployment, the development team must understand how the API will be deployed in the data center or released for outside use from business partners and other users. This includes the use of public or private repositories.
5. API deprecation. Eventually, the API's support and development -- such as bug fixes and performance tweaks -- stops and it is removed from service. Often, it is replaced by a newer version or an entirely different API product to provide similar services.

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.

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.

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.

Challenges of managing APIs

While they are fundamentally built and distributed as software, and share some difficulties familiar to software developers, APIs present several specific challenges.

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:

• Open Authorization (OAuth) for token-based authentication and authorization on the internet;
• multifactor authentication (MFA) and Transport Layer Security (TLS) for authentication, privacy and data integrity between two communicating computer applications; and
• Security Assertion Markup Language (SAML) to share security information about identity, authentication and authorization across different systems.

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.

Management. A business must track all its APIs -- and their versions -- as well as the disparate applications and data sets those APIs connect. It also must ensure that only authorized API users make requests, and that API requests and responses are tracked as well. Management is vital for API visibility, governance and ultimately monetization; if a business doesn't know how many API users make requests, it cannot bill those users for API use.

How to solve this challenge: API mapping tools can help developers understand the messages passed between APIs and illustrate how APIs interact with each other. More broadly, API management is typically performed through a set of tools or a combined platform that performs coordinated aspects of API management.

Components of a successful API strategy

Most organizations turn to an API management platform to support the array of tasks that manage APIs throughout their lifecycle. An API management platform can help to streamline and even automate some of the tasks involved in API development, testing and deployment. API management platforms typically promise five major benefits to the business:

1. Discovery. An API management platform can watch for exchanges between applications, services and other APIs, and can spot new APIs that become available.
2. Version control. Version control helps to ensure that the proper API versions are present in the environment. It details when updates are available and helps to obtain those updates when needed.
3. API distribution. The API management platform can help users deploy an API and port services to the new API.
4. Security. The API management platform can assist in the evaluation of API security, spotting requests or responses that might expose data or a potential attack surface in a workload that employs the API.
5. Tool integration. The API management platform often integrates with other software development toolkits, such as Git or Gradle, ensuring that management capabilities are an integral part of the API lifecycle.

API management tools can be complex, but they typically employ several major components to support an API management strategy: an API developer portal, an API testing environment, an API gateway or an API proxy, an API documentation engine and more.

API developer portal. This is essentially a storefront that allows organizations to see, select, obtain and use available APIs. It offers details about the available APIs, access to documentation such as guides and tutorials, and instructions for installation and integration with developer tools. The portal also frequently includes a change log to help developers understand how the API versions have changed and evolved over time, along with any relevant API status, such as whether the API is unsupported or in end-of-life mode.

API lifecycle manager. All APIs have a product lifecycle that shepherds an API product from inception through end of life. Centralized lifecycle management capabilities in such a platform help organizations ensure that APIs expose and process the right data from the right applications.

API policy manager. Policies use logical statements operated through the API gateway to determine an API's availability and behavior -- how it controls the flow of data, throttles calls, handles variables and so on. An API management tool typically includes an array of default policies out of the box, but organizations can modify and add policies to suit the unique needs of the business.

API analytics. An API analytics engine collects and analyzes metrics related to API use, and produces reports for API developers and other stakeholders. API metrics may include the number of calls, the users making API calls, latency, uptime and availability, CPU memory utilization, errors and trends over time.

API testing environment. Validating an API for reliability, security and performance is a central part of any API strategy. An API testing environment often links to other tools within the developer toolchain and supports multiple test types: functional testing to validate the API's functions, security and error handling; performance testing to gauge how the API handles workloads under stress and variable traffic conditions; and acceptance testing to check the user's ability to employ and utilize the API for its intended purpose.

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, Tyk API Gateway and Express Gateway; cloud platform-specific options include Amazon API Gateway and Azure API Gateway.

How to build an API management strategy

Successful API management does not happen by accident. A business that successfully participates in the evolving digital ecosystem requires a successful API strategy, which typically includes five stages:

1. Set goals. Start with a business goal -- for example, create a new revenue stream for the company's proprietary data and services, or streamline a business process by automating the sharing of data currently done with manual processes. These will guide the technical decisions about how to create and deploy APIs, such as API design attributes best capable of sharing the required data with internal or external users. 
    

2. Consider the infrastructure. APIs ultimately operate within the constraints of the IT and business infrastructure, so understand what resource availability and performance the APIs will require. For example, consider what data is being exposed; its location, such as whether it is in separate financial, human resource or other systems; whether data is single-sourced or aggregated; and whether it is local, remote or in a cloud. Other infrastructure considerations include networking requirements that API access will demand, and the policies, security and regulatory requirements that a business must meet.
3. Start small. Start with small and internal API projects to lower the investment and risks, achieve quick wins, and gain valuable API experience from design through management processes and platforms. Experiment and refine the components of API development, such as design, security, testing and documentation practices. Work with API metrics and analytics to gain experience with API monitoring. If APIs pass initial muster, roll out an evaluation (or "beta") version to broader audiences, and use their feedback to refine the API design and feature set -- and, eventually, release the API to live users for real production work.
4. Manage and repeat. Each API release requires management, monitoring and analytics. This broad phase allows organizations to track API adoption, field help desk tickets, measure performance trends, identify potential security threats and ensure that each API operates as intended. Analytics helps the business shape API adoption plans, guide further API development toward desirable new features and capabilities, and scale the infrastructure as needed over time. The results of management data and analytics also feed back into efforts to set new goals and plans.
5. Build out. With the benefit of initial successes and valuable lessons learned, a business can expand its API strategy through broader releases, improved API versions with additional features and capabilities, and a roadmap of additional new APIs intended to help shape and drive the organization's overall goals.