Guide To Building

an Enterprise API
Strategy
In this handbook:

Guide To Building an
Guide To Building an Enterprise API Strategy
Enterprise API Strategy
STEPHEN BIGELOW, SENIOR TECHNOLOGY EDITOR

Today's businesses run on software, which must interoperate with myriad other software
platforms. But how can a business offer its valuable data and computing capabilities to
countless potential users without revealing the underlying source code and collaborating
with countless contributors?

The application programming interface (API) defines available interactions between pieces of
separate and distinct software to request and present services, all without them actually
knowing anything about the other. This layer of abstraction enables simple execution of
complex interactions.

Consider a restaurant: Diners interact with waitstaff, order from a menu and then enjoy the
meals brought to them. Yet the diners have, and need, no knowledge of how the orders are
prepared, how the kitchen operates or any of the intricate tasks that happen throughout the
restaurant. The waitstaff and menu are the API: The menu defines the choices that are
available, and the waitstaff communicates and delivers those choices and handles payments.

1 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
Just as a well-designed restaurant menu and attentive waitstaff enhance the dining
Guide To Building an
experience, a well-developed enterprise API dictates the scope, quality and security of the
Enterprise API Strategy
provider's interactions with end users.

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.

2 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
API developers can also work with four common types of web service APIs:
Guide To Building an
Enterprise API Strategy
• 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.

3 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
Customer experience. An API's interoperability and ability to add value translates into a
Guide To Building an
superior user experience, customer satisfaction and support. For example, a transportation
Enterprise API Strategy
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.

4 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
WHAT ARE THE USE CASES FOR APIS IN THE ENTERPRISE?
Guide To Building an
Enterprise API Strategy
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.

5 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:

Guide To Building an
Enterprise API Strategy

6 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
WHY IS HAVING AN API STRATEGY IMPORTANT?
Guide To Building an
Enterprise API Strategy
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?

7 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
• Does the API support the business strategy? Does the API support the organization's
Guide To Building an regulatory compliance requirements? Is the API's utilization logged and audited?
Enterprise API Strategy

Read more about application programming interfaces:

API management interview questions and answers

Top API testing training and online courses

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.

8 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
4. API deployment. Once a version of the API is approved for deployment, the development
Guide To Building an team must understand how the API will be deployed in the data center or released for
Enterprise API Strategy 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

9 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
-- for instance, sample software code that employs the API. Other developers must have a
Guide To Building an
clear reference and guide to help write software that can effectively use the API.
Enterprise API Strategy

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

10 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
least-privilege access; and set requirements for graceful error handling and access
Guide To Building an
reporting/logging.
Enterprise API Strategy

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.

11 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:

Guide To Building an
Enterprise API Strategy

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.

12 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
How to solve this challenge: A clearly defined API versioning strategy and careful version
Guide To Building an
control give users backward compatibility and ample time to make necessary changes to
Enterprise API Strategy
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.

13 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
Management. A business must track all its APIs -- and their versions -- as well as the
Guide To Building an
disparate applications and data sets those APIs connect. It also must ensure that only
Enterprise API Strategy
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.

14 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
2. Version control. Version control helps to ensure that the proper API versions are present in
Guide To Building an the environment. It details when updates are available and helps to obtain those updates
Enterprise API Strategy 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

15 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
platform help organizations ensure that APIs expose and process the right data from the
Guide To Building an
right applications.
Enterprise API Strategy

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.

16 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:

Guide To Building an
Enterprise API Strategy

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

17 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
handles workloads under stress and variable traffic conditions; and acceptance testing to
Guide To Building an
check the user's ability to employ and utilize the API for its intended purpose.
Enterprise API Strategy

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.

18 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
There are numerous API management platforms available today, including Apigee (owned by
Guide To Building an
Google), Akana, Azure API Management, MuleSoft Anypoint Platform, Postman, Tibco Cloud
Enterprise API Strategy
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.

19 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:

Guide To Building an
Enterprise API Strategy

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.

20 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY

In this handbook:
3. Start small. Start with small and internal API projects to lower the investment and risks,
Guide To Building an achieve quick wins, and gain valuable API experience from design through management
Enterprise API Strategy 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.

21 GUIDE TO BUILDING AN ENTERPRISE API STRATEGY