02 Develop APIs That Work Properly For The Organization Phases 1 4

Develop APIs That Work Properly for the
Organization
Leverage APIs to connect your systems in today’s web-based world.
Info-Tech Research Group, Inc. Is a global leader in providing IT research and advice.
Info-Tech’s products and services combine actionable insight and relevant advice with
ready-to-use tools and templates that cover the full spectrum of IT concerns.
© 1997-2015 Info-Tech Research Group Inc. Info-Tech Research Group 1
Our understanding of the problem
This Research Is Designed For: This Research Will Help You:

CIOs looking for a way to improve quality and Determine where the use of APIs can enable
development throughput to support business potential business benefits.
priorities. Implement effective, design, development,
Application development managers who want testing and monitoring techniques for API
to understand best practices with API development.
development.
QA and test managers who need to create a
testing practice for APIs.
Outcomes of this Research:

Alignment of API development with business priorities.
Step-by-step approach on how to apply best-practice design and development techniques as it relates
to API development.
Preparation for ongoing evolution of APIs through monitoring and analysis of usage patterns.
Info-Tech Research Group 2

Executive summary
Situation ! Info-Tech Insight
• Organizations are looking for ways to leverage web APIs in order to • Make web API development a
increase app quality, code reusability, and improved development strategic competency that is critical
throughput. to enabling speed of development,
• Organizations are looking for opportunities to create an application quality of applications, reusability,
ecosystem which can expose internal services across the organization innovation, and business alignment.
and/or external business partners. • Design your web API as a product
to be consumed which will promote
speed of development and service
Complication ? reuse.
• Web APIs are regularly designed for short-term code reuse. When they • Incrementally optimize the design,
eventually break, the redevelopment effort is significant. development, testing, and
monitoring of your APIs to cover all
• Web APIs are commonly tested using functional testing through an
use cases in the long term.
application’s user interface. This ignores other testing techniques that are
available, resulting in missed test cases.
Resolution 
• Define the business purpose of the web API and the common uses cases that it will service.
• Understand the development techniques are required to develop an effective web API based on Info-Tech’s web API
development framework.
• Continually improve your web API development approach to demonstrate to business stakeholders the value your web
API provides.

Info-Tech offers various levels of support to best suit your
needs
Consulting
Onsite
Info-Tech Involvement
Workshop
Guided
“Our team does not
Implementation
have the time or the
“We need to hit the knowledge to take this
DIY Toolkit project on. We need
ground running and
get this project kicked assistance through the
“Our team knows that entirety of this
we need to fix a off immediately. Our
team has the ability to project.”
“Our team has already process, but we need
assistance to take this over once we
made this critical get a framework and
project a priority, and determine where to
focus. Some check-ins strategy in place.”
we have the time and
capability, but some along the way would
guidance along the way help keep us on track.”
would be helpful.”
Degree of Customization
Diagnostics and consistent methodologies throughout all four options

Develop APIs That Work Properly for the Organization
– Project Overview
Examine the Monitor and
Test the web
opportunities web Design and develop a web API continuously optimize
API
APIs can enable the web API
1.1 Verify how your web 2.1.1 Understand how your web API fits into your 3.1 Create test cases 4.1 Identify roles for your
API initiatives support system architecture. using model, API development projects.
your overall business 2.1.2 Define high-level design details. synthetic, and 4.2 Develop governance for
objectives. scenario-based test web API development.
2.1.3 Define your process workflows and
design techniques.
business rules. 4.3 Measure the value of
3.2 Create a test plan your web API project.
2.1.4 Map the relationships among data tables
for your web API.
through ERDs.
2.1.5 Document your web API data flow
diagrams.
2.1.6 Identify the integration risks, security gaps,
bottlenecks, and other risks in your data flow.
2.1.7 Define your objects by effectively
Best-Practice referencing your data model.
Toolkit
Determine what Develop a process for designing your web Develop a Develop a process for
value your web APIs APIs to determine your endpoints. process for monitoring your web
offer. testing your web APIs for continuous
Determine how to develop your web APIs
APIs. optimization.
Guided with considerations made for how it will be
Implementations consumed.
Module 1: Module 2: Module 3: Module 4:

Examine the Design your web API. Test your web API. Monitor and continuously
opportunities web APIs Develop your web API. optimize your web API.
Onsite can enable.
Workshop
Phase 1 Results: Phase 2 Results: Phase 3 Results: Phase 4 Results:
• Identification of web • Process flow, ERD, and data flow models. • Web API test plan. • IT governance and
API benefits. • URLs/objects identified. process governance
models for web API
management.

Workshop Overview
Contact your account representative or email Workshops@InfoTech.com for more information.

This workshop can be deployed as either a three-day engagement depending on the client’s level of completed preparation
prior to the facilitator’s arrival onsite.
Day 1 Day 2 Day 3
Workshop Day Workshop Day Workshop Day

Workshop Preparation Itinerary Itinerary
• Verify how your web API • Define your process workflows • Create test cases using model,
initiatives support your overall and business rules. synthetic, and scenario-based
business objectives. • Map the relationships among test design techniques.
• Understand how your web API data tables through ERDs. • Create a test plan for your web
fits into your system • Document your web API data API.
architecture. flow diagrams. • Identify roles for your API
• Define high-level design details. • Identify the integration risks, development projects.
security gaps, bottlenecks, and • Develop governance for web
other risks in your data flow. API development.
• Define your objects by • Measure the value of your web
effectively referencing your data API project.
model.
The light blue slides at the end of each section highlight the key activities and exercises that will be
completed during the engagement with our analyst team.

Use these icons to help direct you as you navigate this research
Use these icons to help guide you through each step of the blueprint and direct you to content related to
the recommended activities.
Guided Implementation
Signifies an opportunity to speak with an Info-Tech analyst to receive tailored advice for your organization on the completion of this
project.
Workshop Activity
Indicates that there are further details regarding the completion of this project while working in workshop setting.
Info-Tech Insight
A symbol of unique insight from an Info-Tech analyst that relates to the completion of the current step of the project.

Phase
1 2 3 4
PHASE
Examine the Opportunities Web APIs Can Enable 1
Phase 1: Examine the opportunities web APIs can enable
1 2 3 4
2.1 Design a Web API 3 Test the Web API 4 Monitor & Continuously
Optimize the Web API
1 Examine the Opportunities 2.2 Develop a Web API
Web APIs Can Enable
Recommended Timeline: 1 week
Info-Tech Insight
• Project launch Deliverables from this Phase
Major
Milestones • Web API benefits
Reached identification No deliverables created for this
Web API development is a tactical phase.
competency that is important for
enabling speed of development,
quality of applications, reusability, Key • Web API project
innovation, and business alignment. Activities aligned with business
Completed objectives

Realize the importance of web APIs in the technology
landscape today
As applications have become more distributed, technologies continued to evolve to
allow for more scalable ways to develop APIs. Web APIs are now the forefront for web
service communication between and within enterprise applications.
∞
Application Architecture Evolution
Monolithic
Application CORBA/IIOP SOAP REST
Libraries
Any change Implementation was Inconsistent APIs Consistent Technological
required would complex and across providers. approach for web Advancements
necessitate a sometimes non- services to make in APIs…
recompilation of the implementable. function calls using
entire application. Costly to implement. GET, PUT, POST,
DELETE.
• Microservices Architecture
Where in web services is REST being applied today? • Enterprise Integration & Development
• Cloud Services (SaaS, PaaS, IaaS)

The growing demand for efficient processes is driving the need
for better integration among services and applications
Business processes cross applications and services as well as leverage data
assets to deliver functionality to users and integrate partners.
Process Orchestration Architectural Components

• APIs – a programmatic interface into an
Transfer
application’s functions, data, or process
Servers
Protocol
External Web APIs
Business that operates over a network.
Internal Web APIs

Web
Users • ESB – a software architecture model

used for designing and implementing the
interaction and communication between
Applications
Transfer ESB mutually interacting software
Protocol applications.
Gateway
Business • Process Orchestration – management

Partner
Partners Data of multi-interaction processes across

business applications and people.
• Application – running instance of a
business software program operated by a
Infrastructure user or a running server program that
responds to requests.
Info-Tech Insight • Partner gateway services and web
servers act as a pipeline, transferring
Organizations that adopt a Service-Oriented Architecture, without proper
information from the business to clients
integration implementation, end up with SOS: Service-Oriented Spaghetti.
and business partners.
Use web APIs to map, manage, and control service interactions regardless • Data – an application data repository.
of underlying implementation to deliver appropriate functionality to • Infrastructure – the underlying
business users.
foundation of the system, which includes
basic support services and hardware.
The goal of web APIs is improved quality and reusability
Web APIs are instruments which enable your development teams to increase the
quality of applications and adopt a “code once, use many” development approach.
Your Organizational Needs

Web APIs enable development teams
to reuse existing code which enables
1. You need a way to develop and maintain faster development.
applications faster. Business users want
applications delivered faster, placing pressure on
IT to quickly release high quality software
1
(develop more with less time).
Web APIs enable
2. The business expects applications to be
development teams to
flexible. With a greater number of organizations Benefits 2
retain flexibility.
embarking on mobile and cloud development
projects, application functions and services are
constantly changing to reflect the evolving 3
business requirements.
3. IT needs a way to integrate business systems
to better support internal processes. Business Web APIs enable ease of
processes often touch multiple systems which transfer of critical data
means application integration is an essential across the organization.
component of delivering value.

Understand the importance of web APIs in the marketplace
Web APIs are an essential component that enable the strategy of an organization.
The apps, data, and APIs that are driving this digital An API is only as valuable as the data or functionality to
transformation are not just enabling business; they are which it provides access. So if an organization delivers a
becoming its very fabric. Whether digital native or particular core competence…it stands to reason that the
analog immigrant, today’s digital pioneers recognize most valuable APIs this organization could provide link
that an app strategy is the key to customer to and drive volume to exactly these core competencies.
engagement, user experience, and business success.
– Steve Willmott. “The Five Axioms of the API
– Promod Hague. “Businesses must embrace the Economy, Axiom #4 – Organizations must provide
programmable world. Or die.” Fortune.com. 2013. core competence through APIs.” 3scale. 2014.
In an effort to leverage the mobile channel more
effectively, enterprises are increasingly exposing data to
mobile developers via APIs. Traditional web service
based on SOAP and designed for a world prior to Industry Facts
ubiquitous mobile computing is being transformed to The first annual API community survey indicates:
REST APIs that are better suited for mobile applications.
• The most common protocols are REST (91.9%)
– Peter Crocker. “Mobile Apps in the API Economy: and SOAP (41.9%).
Avoiding the Mobile Cliff.” Smith’s Point Analytics. 2013. • The most three important factors for APIs are
complete and accurate documentation, service
APIs are the new dial tone…APIs are the connective
availability/uptime, and service
tissue of everything you do.
responsiveness/performance.
– Jeff Lawson, cofounder of and Chief Executive of
Twilio as quoted by Dean Takahashi. “The new dial DuVander, Adam. “API Consumers want reliability,
tone: How the API economy accelerates the growth of documentation, and community”. ProgrammableWeb. 2013.
cloud apps.” The API economy panel at CloudBeat.
2013.
Web APIs should enable business strategy execution
There are real above-the-line and below-the-line benefits that web APIs can unlock.
Most significant business motivation for using web APIs: Most significant technical motivation for using web APIs:
75% of organizations want to connect to more partners. >80% of organizations want to integrate applications.
APIs enable flexibility in terms of partners Organizations using web APIs found that they:
connecting to web services…APIs let you put • Increased their customer/partner reach by 50%.
business logic and services in a centralized spot. • Increased the number of platforms reached by 57%.
This logic can be reused and it becomes incremental • Increased the number of apps built from web APIs by 50%.
to expand to different devices.
…APIs enable an increase in traffic and usage Organizations using web APIs found that they:
by enabling developers and partners to more • Increased web/device traffic by 70%.
easily develop apps that tap into a company’s • Increased web service usage by 58%.
online services.
…APIs lead to developer/partner productivity Organizations using web APIs found that they:
improvements and create an environment that • Reduced the time it took to onboard partners by 30%.
supports innovation. • Increased partner productivity by 30%.
Source: Fern et al. “Web API Study: The Benefits of APIs in the App Economy.” Hurwitz & Associates. 2011.

Unfortunately not everyone is doing web API development
effectively
Both development and runtime issues prevent high adoption of web APIs, leading to
less than adequate business benefits realization.
It’s all too common that web APIs are not adopted due to development and runtime issues the APIs cause for consumers.
Bottom-line: consumers won’t come back to your API if it returns a negative experience the first time around.
At 22:30 CST, the FedEx Shipping API became
unavailable. Due to FedEx’s lack of proper
It is critical for your organization to adopt the appropriate
timeouts, this is causing requests to backup for
development practices for web APIs in order to minimize both the Shipping Service and all Storefronts.
the following problems from occurring. – Bigcommerce Status Report. 17 Jan. 2015.
…requests to most Google APIs resulted in 500
DEVELOPMENT ISSUES error response messages…a configuration change
• Bad documentation: API consumers don’t know how to use the web API was inadvertently released to our production
properly. environment without first being released to the
• Versioning problems: API changes lead to compatibility breaking causing
testing environment. The change specified an
a lot of rework for anyone using the API.
• Unexpected behavior: When API changes are made, the interface invalid address for the authentication servers in
remains compatible, but the internal logic has changed, causing retesting production.
and recoding for API consumers. – Google Developers Blog. 3 May 2013.
RUNTIME ISSUES Indicators of a Poor Web API

• Poor performance: The API takes too long to execute or has severe • API consumers request a copy of your data
limitations on how it should be used. (rather than using your API to access it).
• Version changes break compatibility: Deployment causes several • API consumers are not informed of changes
integrations to break because of lack of compatibility. made to your API.
• Intermittent failures: Errors that are hard to replicate but known to exist.
• API consumers do not find your API easy to
use.

Use web APIs to enable below-the-line process improvement
Adopting an API-enabled application ecosystem enables your

organization to improve internal processes. Utilizing APIs to
abstract access to backend services within your organization
creates a fast-moving, flexible infrastructure for your developers
to work with.
• Using web APIs across
• Data access can often • APIs can not only
the organization can
become frustrating and enable your business
help build awareness of
complex when working to manage internal
what services and data
with multiple business processes, but also
files are available for
groups. potentially lead to
business units to use.
• Used appropriately, your creating new
• If used correctly, APIs business value
API speeds up system
can enable your chains by arranging
integrations for
business to organize existing services,
improved business
internal systems to data, and
agility and provides a
reduce maintenance functionalities into
common path for
costs and support the new and valuable
transactions to flow from
creation of innovative configurations.
which can potentially
products and services.
lead to a more efficient
allocation of resources.
A study conducted by McKinsey Global Institute estimated that organizations can improve productivity levels by
20 to 25 percent by improving internal collaboration through the use of an internal API.
Source: Boyd. Mark. “6 Business Benefits of Private APIs”. Nordic APIs Blog. 2014.

Use web APIs to enable above-the-line revenue generation
Consider the possibility that your internal services can be

monetized through your web API. Consider how valuable your
internal services can be to external third parties and business
partners. Services like data transfer and partner integration are
potential opportunities where your organization can take
advantage of using an API.
It is important to consider what type of monetization model you will take on, what your API should charge, and who will pay
for API usage. Depending on what services you provide with your API, certain methods of charging API consumers may be
more appropriate than others.
Pay As You Go Tiered Pricing Freemium In order to monetize

your API, it is critical to
$10/month for first 500
transactions Free Trial understand how your API is
Upsell… being used. And the way to
understand how your API is
Pay for what you use.
$0.80/month for next 100
transactions… Try before buying. being used is through
appropriate monitoring tools and
metrics. Deploy a few monitoring
Unit-Based Pricing Transaction Fee
initiatives at first and increase
$70 for 1300 $0.05 every time you
the level of monitoring as
$50 for 500
$60 for 900
transactions
transactions call me. adoption of your API increases.
transactions
Source: Pedro, Bruno. “How to Monetize your
Fixed prices per number of service Source: Musser, John. “API Business Models.” API”. Nordic APIs. 2014.
calls. API Strategy Conference. 2013.
CASE STUDY Wine.com leveraged REST APIs and the cloud to allow
Organization mobile enablement and quick delivery of information
Wine.com
Applicable API Use Cases

Industry
Mobile Introduce New Deliver Info
Retail
Enablement Revenue Stream Quickly
a le
3 sc
e:
urc
So
Situation Solution Results
• Wine.com strives to be the primary • APIs were built using REST • Created brand awareness through
resource for wine enthusiasts by principles and the retrieved content third-party applications.
providing helpful information. can be in XML or JSON format. • Leveraged new customer channels
• The goal was to provide • Wine.com chose a cloud API without additional IT resources.
developers access to its wine management solution to provide • Included mobile in-app commerce
catalog and related content in an easy and rapid integration and with selected partners in order to
open and accessible way. quick distribution of information. develop new revenue streams.

CASE STUDY Walgreens extends its photo printing services with
Organization QuickPrints APIs to open a new revenue stream
Walgreens

Industry
Brand Introduce New Promotions
Retail
Awareness Revenue Stream
b
leWe
e: ab
ourc amm
S gr
o
Pr
Situation Solution Goals and Results
• Walgreens realized that the • Walgreens began offering its

• Provided a convenient and
average annual spending per QuickPrints API to third-party
automated self-service photo
customer increases four times developers in 2012 to provide
delivery.
when store services are available mobile in-app photo printing
• Communicated and developed
on mobile and in store. services for home delivery or pick-
new pathways for customers into
• “Walgreens is focused on providing up at a store.
the Walgreens brand using mobile
[its] customers the ability to • It offered a revenue sharing
devices.
interact with [its] brand through all program to developers for print
• Established itself as the preferred
possible channels.” Source: orders and products purchased
photo printing service.
Apigee with the API.

CASE STUDY Microsoft designed its solution architecture around
Organization reusable and scalable API designs
Microsoft

Industry
Establish API Scale Business Reuse &
Computer
Standards Services Share APIs
Software
and
Hardware Key Business Benefits
• Consistent user experience.
• Improved app design quality and
business process execution.
e: • Development time was reduced and
o urc soft
S cro duplication of effort was less common.
Mi
• Microsoft CEO announced its drive • Microsoft developed an API-centric

architecture which focuses on • Development teams were able to
to be “mobile first, cloud first.”
reusable APIs that provides apps focus on the development and
Support for apps on multiple
access to core business services enhancement of business
platforms across a large number of
and data, and integration with key solutions instead of integration with
business functions has become
platforms. utility services.
more complex.
• Design patterns and practices • App modifications and upgrades
• A standardized API development
were established to promote became easier.
environment was needed to
reusability standardization and • Infrastructure requirements and
provide scalable, reliable, and
ability to share among multiple overall design became simpler.
efficient app environments.
development teams.

Exercise: Verify how your web API initiatives support your
overall business objectives
1.1 1.5 Hours
Based on the applications in which you plan on exposing to the web API, Info- INPUT
Tech recommends conducting a before and after survey to determine how
satisfied users are with using a non-web API enabled application and a web API • Business objectives
enabled application.
Instructions OUTPUT
1. On a whiteboard, write down your business objectives. Some examples include: • Web API
• Increase client reach through engaging marketing campaigns. development
• Reduce business operation costs. initiatives prioritized
• Create innovative products to remain competitive in the market.
2. Map the objectives to use cases that will allow you to realize these objectives. Some use
cases can be mapped to multiple objectives. Materials
3. List IT solutions that are web API enabled and will support your use cases. • Whiteboard and
4. Prioritize your use cases and business objectives based on value to your business. This markers
step is a valuable step in determining which web API development projects to embark on
first. Business value definitions can include the following drivers:
• Revenue generation
•
Participants
Cost savings
• Compliance • CIO
• Strategic importance • IT Director
• Dev Manager

Exercise: Verify how your web API initiatives support your
overall business objectives (continued)
1.1 1.5 Hours
Instructions INPUT
• Business objectives
5. Determine what metrics will be used to measure and monitor the effectiveness and
business value of your web API. Determine metrics that map back to business objectives.
Metric Type Metric Business Objective

OUTPUT
Traffic Total calls made to API
Top methods used • Web API
Call chain patterns development
initiatives prioritized
Service Availability
Error rates
Code defects Materials
Support Ticket support rate • Whiteboard and
Ticket response time markers
Developers Total developers using API

Active developers using
API Participants
retention rate • CIO
Source: Musser, John. “What Makes a Great Open API?”. OSCON2012. 2012. • IT Director
• Dev Manager
See the following slide for an example of how Exercise 1.1 is mapped out.

Exercise: Verify how your web API initiatives add value to
overall business objectives (continued)
1.1 1.5 Hours
Example:
Business IT Solutions – Web
Use Cases
Objectives API Enablement
1. Improve customer retention Send out promotions

Measured value metric: Number of calls
Partner Integration
to web API that supports customer
marketing Implement loyalty
program
Customer Data
Proactive Integration
2. Improve service experience communication
to web API that provides customer data Insight-driven
support
Self-Service Portal
Update work orders
3. Optimize field service productivity at work site
to web API that provides data to remote
users Push work request to
nearest worker

Info-Tech Thought Model: Optimize the design, development,
testing, and monitoring of your web APIs
STEP 1 Re/Design STEP 2:Develop

Develop your web API with the following in mind:
Determine the purpose Design your web API using:
of your web API Pagination
Content Error
code reuse Process Flow Negotiation Handling
data end user
external
purpose
transformation
ERD
use cases
external layout Caching

Payload
REST HTTP
Data Flow
internal Security API SDKs
Concerns
STEP 4 Monitor STEP 3:Test

Monitor your web API to determine versioning: Create API test cases using effective methods/tools:
Versioning? Analysis Test Techniques Code Changes
Interface Changes
Schema Changes
Governance CI Tools API Call Sequence
Changes
Test Cases Security Tests
API Consumer
Feedback
Web API Test Tools Usability Tests
….
• Optimize the design, development, testing, and monitoring of your APIs incrementally and iteratively to cover all
use cases in the long term.
• Once you’ve created an initial web API, determine if it needs to be versioned based on API consumer feedback, process
changes, and analysis from monitoring initiatives. If this is the case, iterate through the web API development model to
include the use cases realized during monitoring.

Follow Info-Tech’s methodology for undergoing a process for
designing, developing, testing, and governing your web API
Leverage Info-Tech’s repeatable development process to improve the

quality, reusability, and governance of your web APIs.
Design & develop a web API

2.1.1 Understand how your web API fits into your system architecture.
2.1.2 Define high-level design details.
2 2.1.3 Define your process workflows and business rules.
2.1.4 Map the relationships among data tables through ERDs.
2.1.5 Document your web API data flow diagrams.
2.1.6 Identify the integration risks, security gaps, bottlenecks, and other risks in your data Each phase will
flow. run you through
2.1.7 Define your objects by effectively referencing your data model. a series of
exercises in
3
Test the web API order to develop
3.1 Create test cases using model, synthetic, and scenario-based test design techniques. a complete
3.2 Create a test plan for your web API. process for
developing your
web API.
Monitor and continuously optimize the web API

4 4.1 Identify roles for your API development projects.
4.2 Develop governance for web API development.
4.3 Measure the value of your web API project.

Phase 1 outline
Call 1-888-670-8889 or email GuidedImplementations@InfoTech.com for more information.
Complete these steps on your own, or call us to complete a guided implementation. A guided implementation is a series of 2-
3 advisory calls that help you execute each phase of a project. They are included in most advisory memberships.
Guided Implementation 1: Examine the Opportunities Web APIs Can Enable

Proposed Time to Completion: 1 week
Phase 1: Examine the Opportunities Web APIs Can Enable

Start with an analyst kick off call:
• Discussion on your web API development project alignment with business objectives.
• Discussion on priority levels for different web API development projects based on business priority.
Then complete these activities…

• 1.1 Verify how your web API initiatives support your overall business objectives.
With these tools & templates:

No tools or templates for this GI.
Phase 1 Results:
• Understanding of business alignment with web API development initiatives.

If you want additional support, have our analysts guide
you through this phase as part of an Info-Tech workshop
Book a workshop with an Info-Tech Analyst
• To accelerate this project, engage your IT team in an Info-Tech workshop with an Info-
Tech analyst team.
• Info-Tech analysts will join you and your team onsite at your location or welcome you to
Info-Tech’s historic Toronto office to participate in an innovative onsite workshop.
• Contact your account manager (www.infotech.com/account), or email
Workshops@InfoTech.com for more information.
The following are sample activities that will be conducted by Info-Tech analysts with your team:
Verify how your web API initiatives support your overall business
objectives
1.1
An Info-Tech facilitator will discuss what Info-Tech is seeing trending in the API
development landscape and how these trends can benefit your organization. The
facilitator will assist in identifying web APIs that support your prioritized business
objectives.

Phase
1 2 3 4
PHASE
Design & Develop a Web API 2
Phase 2.1: Design a web API to determine endpoints
1 2 3 4
1 Examine the Opportunities 3 Test the Web API 4 Monitor & Continuously
Web APIs Can Enable Optimize the Web API
2.1 Design a Web API
2.2 Develop a Web API

Recommended Timeline: 3 weeks
Info-Tech Insight • Web API design Deliverables from this Phase

Major created.
Milestones • Understanding of best
Reached Design
practice development
Requirements
Design your web API that promotes techniques.
speed of development and service
• Creation of business
reuse. Key Web API Design
process flow, ERD,
Activities and data flow
Completed diagrams.
• Collection of data sets
defined (as objects).
Phase 2.1: Exercise Guide
Design your web API that promotes speed of development and service
reuse.

2.1.6 Identify the integration risks, security gaps, bottlenecks, and other risks in your data
flow.
2.1.7 Define your objects by effectively referencing your data model.
3
Test the web API
3.1 Create test cases using model, synthetic, and scenario-based test design techniques.
3.2 Create a test plan for your web API.
Participants
Business Analyst(s)
Monitor and continuously optimize the web API Development Manager
4 4.1 Identify roles for your API development projects. Data Architect

Navigate through this blueprint using the following definitions
as they relate to web API development
“The exchange of information resources facilitated by exposing your core entity’s

API Economy information resources to an ecosystem of developers through an internet-based API,
and combining other entities’ APIs to build new information resources.”
Source: Jim Plamondon. “Introducing the API Economy: A Dialogue.”
An application programming interface designed to operate over the network using

Web API web protocols.
An entity that provides/exposes the

API Provider web API. Internal/Private Web API
An off the shelf or custom application An API used to enable internal API consumers to
API Consumer that uses the web API. operate within the firewall of the organization.
A business stakeholder that uses an

End User application which internally makes use
Open/Public Web API
of the web API.
Source: Israel Gat and Giancarlo Succi.
An API exposed to API consumers outside the
firewall of the organization as well as internal API
consumers within the firewall.

Make your web API reusable and not tied to a single business
process or application
Web API exposed to a given business
process/app.
• Design technology-agnostic APIs. This creates a shift in mindset
where web APIs move away from single point-to-point coupling (via a
Request single POST SOAP call, for example) to loosely coupled, multiple
Web API Business
Process
exposed resources for numerous applications and business
processes to take advantage of (via REST with multiple HTTP verbs
App Data
exposing resources, for example).
Response Data • Make your web API generic. There could be any number of
scenarios to access your web API. It should service more than one
process/application so that it is re-purposable and reused in various
Web API that is service oriented. ways. An example of this is the REST architectural style which
exposes a generic entity without being tightly coupled to a specific
Multiple process or application.
Request/Response
Interactions • Developing your APIs with the mindset of “code once, use many”
leads to simplified maintenance due to reusability, making it easier
for developers to understand and consume.
Multiple
Business
• Decouple formatting from data. The same URI should return data
Web API
Processes in JSON, XML, HTML, or any other format since it references the
same resource. Avoid different URIs for each format.
App Data
For more information on service orientation, refer to Info-Tech’s

research, Build an Application Integration Strategy.

Exercise: Understand how your web API fits into your system
architecture
2.1.1 1.5 Hours
Use a consistent, standardized method to design, build, and deploy API solutions.
INPUT
• Even though organizations plan for integration initiatives in their projects, very few have
developed a holistic approach to their integration problems, resulting in each project • Existing business
deploying different tactical solutions. process documents
• Architecture provides the footings, boundaries, definitions, and dimensions of information
and application integration with your integration technologies such as ESBs and APIs.
• Without an architectural view, it is difficult to align API integration technology solutions with OUTPUT
business drivers.
• High-level system
architecture
Instructions
1. Develop a high-level system architecture in context of developing your web API with
architectural components that apply to your organization (e.g. ESB, process Materials
orchestration, web servers, partner gateway services, data, infrastructure).
• Identify specific entities pertaining to architectural components, each unique to • Whiteboard and
markers
your organization (e.g. corporate database for data architectural component).
• Web API Design
• Identify how the APIs you are developing are connected to application
Document Template
architectural components. This will drive how your API will be designed in
exercises 2.1.2 through 2.1.7. Participants
2. Document Step 1 into the Web API Design Document Template. Giving your
developers a web API design document provides them with development guidelines on • Business Analyst
interfaces and data payloads, and also gives your operations group guidance on what to • Development
expect for performance, integration, and network connectivity components. Manager
Refer to the following slide for an example of the final output of this exercise.

Exercise: Understand how your web API fits into your system
architecture (continued)
2.1.1 1.5 Hours
Example:
Process Orchestration BPM
Legend:
Corporate
Website HTTPS
CRM Apps Web API being
Business
Web developed
Server ERP Apps
Users
External Client ECM

Information HTTPS
Legacy Apps
Business
Partners Partner
Gateway API
s Corp. Database Private Cloud
Infrastructure
Common Infrastructure Services Process Orchestration Components

• Security Services – include security protocols and procedures for • Business Processes – process rules and definitions
components operating in AI environment. that are imported into the process run-time engine for
• Audit Services – trace data flowing through ESB from service requestor to automated execution.
provider and distribution of data. • Human Tasks – staff activities in a process assigned
• Monitoring and Management Services – manages system and business to, and management of, the tasks.
processes. • Business State Machines – service that maintains the
• Metrics Capture Services – captures and stores operational metrics for state of long running processes.
analysis. • Business Rules – rules stored in a repository and
• Directory and Access Services – provide directory of physical locations of implemented via a rules execution engine.
resources and end points.

Use well known web API design guidelines to prevent common
errors
A web API is exposed through HTTP as a set of generic
The Importance of API Design resources that are ultimately based on a well-defined data model.
A focus on design is a key part of ensuring user productivity Data Model Object Representation
and a good ROI for the solution. A poor design will frustrate
developers and lead to longer development cycles or complete App Interface HTTP
abandonment of the solution. A well-designed web API will be from_resource()
simple to understand, consistent in its usage, and stable. application/x-resource

to_resource()
Well-designed web APIs tend to get reused – this leads to a App Web API API
higher return on the investment, improved code quality through Consumer
reuse, and design simplification. Source: Jansen, Geert. “The Job of the API Designer.”
• In the design stage, expect to go through several iterations before settling on a stable It is worthwhile saying that you
web API. It is more cost effective to design a web API with initial expected should develop an API with the end
functionality and include additional features once more use cases come to light. user in mind, and it’s something that
◦ Determine and document what your web API is trying to accomplish for your needs to be reinforced continually.
web API consumers. The people providing the API as a
◦ Determine what the use cases of your web API will be. Brainstorm and interview service have a certain perspective on
as many potential web API consumers as possible to determine these use cases. the technology they’re building. It’s
◦ Determine how these use cases would translate into specifications for your web necessary to be able to step out of that
API. Keep these specifications short as they will be easier to modify. Determine perspective and consider the
each specification’s appropriateness to the web API. For API specifications, technology being used to implement
categorize each specification into: (1) routines, (2) data structure, (3) object class, the clients to the API and what those
(4) methods, (5) parameters, and (6) variables. client developers are trying to
- When in doubt, leave it out. It’s better to leave out specifications that you achieve.”
are unsure of. – Ken Toole, Senior Director of
Engineering at Adobe Systems
Run your design sessions as a product development effort
aimed at the consumer of your web API
Establish the key objectives for your web API in order to obtain the right
resourcing to deliver a suitable product.
Involve Key Stakeholders Info-Tech Insight
• A team of development and data experts need to be intimately involved at • API development is driven from the
this stage as there are many possible implementations for a given set of outside in with clear intent. What you
business requirements.
• Also, consider including the following roles:
are trying to achieve will drive many of
o Business Process Owner the design decisions and make it
o Test Lead easier for web API consumers to
understand. It is aimed at improving
the productivity of those who will
Follow Best Practices consume your API.
• Use a multi-pass design approach, where optimization is progressive.
• Conduct an ongoing cost/benefit analysis looking at the trade-offs • Don’t count on your initial API
between short- and long-term objectives. design reaching stability right away.
• Sometimes a less than optimal solution is necessary so that the overall Design efforts can continue for a long
organization benefits through standardization. time since it is an iterative process. Aim
for a minimum viable product at each
We try to provide APIs that are clear in their intent and usage so that iteration rather than trying to over-
you can avoid having clients make assumptions that are invalid. As a engineer a web API.
service provider, you have to take a bit of ownership over, “Did you
provide an API that allowed clients to do things that become • Document your changes as part of
problematic in the future, or were you very clear and explicit about an overall enterprise architecture.
how your API should be used in the design of the API itself?” This will enable discussions related to
– Ken Toole, Senior Director of Engineering at Adobe Systems impact analysis for process or system
changes to be simplified.
Use these best practices to define API requirements, use cases, and
design entities in the next exercise.

Exercise: Define high-level design details based on web API
requirements
2.1.2 1.5 Hours
Instructions INPUT
1. As a team, define your web API requirements (business, functional, non-functional). • Web API use cases
Brainstorm the use cases of how your web API will be used by API consumers. For more from the business
information on defining requirements and use cases, and design techniques, please refer to
Info-Tech’s blueprint on Application Development.
2. Using the sticky notes and the whiteboard, define design entities for your web API based on OUTPUT
requirements. Map design entities to the requirements and use cases of your web API.
• Web API use cases
3. Document steps 1 and 2 in the Design Requirements Template.
• Design entities for
web API
RQMT RQMT RQMT
1 2 3 Materials
• Whiteboard and
markers
USE • Sticky notes
CASE • Design Requirements
USE USE Template
USE
CASE CASE
CASE
Participants
• Business Analyst
• Development
DESIGN DESIGN Manager
DESIGN ENTITY ENTITY
ENTITY DESIGN
ENTITY

Design and document detailed web API functionality around
the consumer of your web API
Define the dialogue between the web API and its consumer that satisfies the
requirements and processes set by the business.
• Business process owners can collaborate on improving existing processes based on the design entities
and requirements set out in Exercise 3.1.
• In some cases, multiple processes can benefit from a single web API.
• Use the detailed design to provide context for business use cases which, in turn, can be used to create
functional test cases for applications that make use of each web API.
Make It Happen:
• List all the business rules in a given process. This can be done by initially looking at decision points
within each process flow. You can create test cases to ensure your web API works under those
conditions.
• Determine the URI filters based on how your web API will be consumed. If, for example, most
cases only require a subset of the entire data available, don’t send all the data unless a particular flag
has been set in the URI.
• Design your web API to be consumed easily. If the API consumer is expecting JSON data, for
example, but your web API only offers XML, that will require additional development effort which could
make your web API less attractive.

Exercise: Define your process workflows and business rules
2.1.3 2 Hours
Instructions INPUT
1. Map the high-level step-by-step process of the use case to show your best estimate at the
• Existing business
intent of how the web API will be used.
process documents
2. Identify where business rules exist in the process workflow.
3. Identify which business processes belong to a specific application/system. Then, identify
where web API integration is required. OUTPUT
4. Document steps 1 through 3 in the Web API Design Document Template.
• Business process
Example:
workflow
Above/Below $5,000
Budget?
Materials
Create a Get Finance Generate Email
• Whiteboard and
Campaign Approval Below Budget List
markers
• Web API Design
Above Budget Document Template
JSON
Get Additional data Participants
exchange
Funds • Business Analyst
• Development
Manager
Push Emails
Launch
Into Email
Campaign
server
Map the relationships among data tables through Entity
Relationship Diagrams (ERD)
Use ERDs to document the relationships and understand the construction of
objects exposed by your web API.
Why is it important?
• You need to understand how internal objects are connected for maintenance purposes. Entity
relationship diagrams describe how one data set (entity) uses or points to another entity. Actions indicate
the purpose or logic behind the use of each entity.
• Your data may be coming from different systems that require customization to support your web
API. The ERD could be an abstracted view of a database and the relationships among multiple
databases which all need to be based on the same semantic understanding.
• To serve as a framework for developing wireframes and storyboards. Each entity can be an
interface with each data type as an interaction object and in which the action defines the interactions
between the wireframes of a storyboard.
How should ERDs be created and documented?
• Elicit process descriptions and make all nouns into entities, noting any hierarchical dependencies
between them.
• Begin with an end user or requirement and flush out the types of data required to support each use
case.

Exercise: Map the relationships among data tables through
ERDs
2.1.4 1.5 Hours
Instructions INPUT
1. Determine hierarchical model will be used to create your entity-relationship diagram (Class
• Documentation on
Type, Ownership, or Association).
data sets
2. Denote all data sets into data tables. Map data tables that will be specifically exposed by
the web API being developed. If you are not certain which ones will be exposed, include all
data tables that you would think would be valuable to the API consumer.
OUTPUT
3. Map relationships among data tables. This will depend on the hierarchical model used.
Make sure to define the actions between entities which will map the interaction workflow • Entity relationship
from one data set to another. diagram
4. Document steps 1 through 3 in the Web API Design Document Template.
Example:
Materials
Campaign Customer Organization
• Whiteboard and
Name FirstName OrgName markers
• Web API Design
Description LastName Address
Document Template
StartDate Role Phone
Participants
EndDate Organization City
Type Revenue • Data Architect

Invoice
• Development
Channels InvoiceNumber Manager
Description Items
Availability Date

Document your web API inputs and outputs through data flow
diagrams
Why is this important?

• Exposing the appropriate information and data is critical for your web API to be successful. Without the
right data, there is risk of disruption to the business.
• Identifying data inputs and outputs can lead to discussions around establishing the true source of data
within the enterprise.
• It can help assess the payload necessary and provide insight into network traffic and possibly
performance issues.
How is it typically done?

• Standard practice is to use a data flow diagram. The diagram traces all data from creation inside the
web API to final consumption and storage.
• In some cases data may not be immediately available due to dependencies from other systems, which
leads to discussions around workarounds. Temporal aspects of data are documented in the data flow
diagram.
• Security restrictions should be documented in the data flow diagram including firewall port requirements
and payload limitations.

Exercise: Document your web API data flow diagrams
2.1.5 2 Hours
Instructions INPUT
1. In process flow-like diagram, determine how each data set relates to another using verbs • Documentation on
that are based on HTTP methods. data sets
2. For each data set, determine all associated attribute variables and function methods.
3. Identify in your data flow diagram where data integration is required. This will be where your
web API be located. OUTPUT
4. Consider the following when conducting this activity:
• Is the data read-only or can the application and users edit and modify it? • Data flow diagrams
• Which components are managed and operated by third-party providers? What is
your level of control?
• What is the taxonomy of data in your system? Is it standardized and is the data
encrypted? Materials
• How often are your databases updated? Is it real-time or periodic extract, transfer,
• Whiteboard and
and load (ETL)? markers
Example: • Web API Design
Customer Account Manager Document Template
GET Account Manager
FirstName Name Participants
POST Customer
LastName Customer • Data Architect
• Development
Role Level CRM ERP
Manager
Organization
API
Type Private Cloud

Exercise: Identify the integration risks, security gaps,
bottlenecks, and other risks in your data flow
2.1.6 1.5 Hours
• APIs are critical components of your system architecture which provide access to native INPUT
hardware features and facilitate communication with enterprise systems, third-party
services, and other devices. • Documentation on
• By not paying attention to your API development, you risk: data sets
o Heavy-weight communication over slow mobile networks which will drive down
performance.
o App misuse due to exposed and unsecured APIs. OUTPUT
o Unavailable services because APIs do not accommodate changing end points
and fragmented data schemas. • Data flow diagrams
• Identifying potential risks associated with data exposed by your web are important when
determining the development practices that need to be used to mitigate those risks.
Instructions Materials
1. Using your data flow diagram as a reference, identify existing and potential • Whiteboard and
markers
performance bottlenecks, security gaps, integration issues, and other • Web API Design
technical issues. Document Template
2. Write your gaps on sticky notes and place them on top of your diagram.
3. Determine development-related practices that mitigate the identified risks for Participants
successful API development. Write these practices on sticky notes and place • Data Architect
them on top of the gaps on your data flow diagram. • Development
Manager
Refer to the following slides for leading questions to reveal current or potential security,
performance, and integration risks in your data flow and for an example of the final output of this
exercise.

bottlenecks, and other risks in your data flow (continued)
2.1.6 1.5 Hours
Leading questions to ask when assessing your API data flow:

Security Performance Integration
• What data needs to be secured • What may cause performance • What information and data are
during transit? bottlenecks with in-house servers exchanged within your flow? Does it
• What might cause data to be (e.g. server load balancing issues, need to be secured?
tampered with? internet connection)? • What integration approaches in your
• What data is trusted vs. untrusted? • Is the load properly distributed stack are not scalable to increased
• Do work products from partners, across various device hardware and loads (e.g. point-to-point, adapter,
collaborators, subcontractors, or system components? ESB, middleware, API gateway)?
suppliers meet your security • How many tasks are suspended and • Is your API dependent on other
requirements? delayed due to slow executions of applications, hardware, or systems?
• Is the application able to adapt to other tasks? • What web communication protocols
changing circumstances that affect • What level of control do you have and standards are used by existing
its ability to meet its security over backend infrastructure and the applications, data, APIs, and
objectives? code of your applications? infrastructure? Are they scalable?
• Do the architecture and design • Does the frequency of data • What is the format of the payload
sufficiently address security? refreshes consume significant transported over your APIs (e.g.
• Are end users and administrators battery and processing power? XML, JSON)?
verified upon application spin up • Does information flow through a • What level of customization do you
and spin down? single module, an API, or hardware? have over your third-party APIs?
• Does the system comply with • Do your applications heavily rely on • Are your APIs standardized and
applicable security policies, laws, the web for operations? documented?
and regulations?

bottlenecks, and other risks in your data flow (continued)
2.1.6 1.5 Hours
Example:
High Payload, Data
Encryption
Legend:
Slow
Application CRM
Execution
ERP
API Risk of Data Performance
Consistent
Leak Issue
Object
Notation
Data Customers Account Manager Security Gap
Managed by Integration
Infrastructure Corp. Database Private Cloud
Third Party Risk
Solution
Customer Account Manager
GET Account Manager
FirstName Name
POST Customer
LastName Customer
Role Level CRM ERP
Organization
API
Type Private Cloud

Define your objects by effectively referencing your data model
Info-Tech recommends using a REST architecture style for API development.

Define the objects that your web API will expose (endpoints).
• Focus on how your objects are defined and less on data representation. Within the data that you exposing, it is important to
determine how a collection of data sets will be represented for API exposure. Define objects that are intuitive for your API
consumer to request for. Representation formats for data (e.g. XML, JSON) are always changing – ensure that you are able
accommodate for these appropriately (demonstrated in the content-type of a request).
• Define objects as nouns and plural-based. A collection of data sets indicates that there is multiple entities associated with a
object – make your objects intuitive for the API consumer. Objects should also be noun form (e.g. /customers, NOT
/getcustomers) for scalability at the API layer.
/customers Web Server
API
GET /customers
Consumer calls
Content-Type: application/json
Request Customer Location
Data Set
Data Modeling Account
(Collection)
Class Design Considerations

• Minimize the amount of change that occurs by defining classes/data sets as immutable. If you do design your web API to
have mutable classes, keep them well-defined and be clear when it is legal to call specific methods. Having immutable classes
and thereby objects will make your code thread-safe and reusable in the long term.
Method Design Considerations
• Adhere to consistent semantics throughout the API, other APIs, and connecting platforms. Keeping naming conventions of
requests consistent with other software components will create less hardship for maintenance in the long term. An approach is to
keep your actions separate from your objects for your methods (e.g. HTTP methods GET, POST, PUT, DELETE).
• Avoid long parameter lists to avoid payload issues for responses. This can be done by either using the break up method or
creating a helper class to house parameters.
• Use consistent parameter orderings across methods. Regardless of the parameter’s semantical significance or the
importance to a particular method, it is more important to have parameter orderings consistent where possible for greater API
performance.
Source: Bloch, Joshua. “How to Design a Good API and Why It Matters”.

Exercise: Define your objects by effectively referencing your
data model
2.1.7 1.5 Hours
Instructions INPUT
1. Based on the data flow diagram created in 2.1.3, group data sets into objects. Name the
objects in plural and as nouns. • Documentation on
data sets
2. Document step 1 in the Web API Design Document Template.
OUTPUT
Example:
• Data flow diagrams
/customers with web service
objects defined
Customer Account Manager

Materials
FirstName Name
GET customers
• Whiteboard and
LastName Customer markers
CRM ERP • Web API Design
Role Level
Document Template
Organization
API Participants
Revenue
Private Cloud • Data Architect
• Development
Manager

Phase 2.2: Develop a web API with considerations made for
how it will be consumed
1 2 3 4
1 Examine the Opportunities 3 Test the Web API 4 Monitor & Continuously
2.1 Design a Web API

Recommended Timeline: Two Months
Info-Tech Insight • Understanding of best- Deliverables from this Phase

Major practice development
Milestones techniques.
Reached No deliverables created for this
Be consistent end-to-end when phase.
developing your web API. Target
developers will find your API easy to
• No activities for this
adopt if your API base format is Key section.
similar to their application. Activities
Completed

Develop your web API with HTTP override to allow
consumption through firewall restrictions
When It Should Be Used
HTTP Override Example:
• If the client side won’t support a particular
HTTP verb that you have built into your
design. This allows web API clients to use POST /customers/cust1
your services in accordance with their
Host: myuri:8080
firewall restrictions.
Content-Type: application/json
X-HTTP-Method-Override: PUT
How HTTP Override Works Cache-Control: no-cache
• The client side injects a X-HTTP-Method- Example Description:

Override header in the request.
• The client side submits a POST request which needs to
• Your API accepts the request, looks for the be redirected in your web API as a PUT request.
X-HTTP-Method-Override header, and
redirects the request using the appropriate HTTP/1.1 200 OK
POST /customers/cust1
verb. ...
…
• The client side receives the appropriate
information.
Considerations
Web API API
Consumer
• Be prepared for extra development and
testing required to support the override.

Include content negotiation to prolong the stability of your
web API
Content Negotiation Example:
• When you want a single resource-based
URI endpoint to output data in multiple
formats. This type of design promotes long-
term reuse and separates format from the GET /customers/cust1
resource. Accept: application/json
application/xml; q=0.8
application/rss+xml; q=0.5
How Content Negotiation Works
• The resource URI is called by the client side Example Description:

along with an Accept request header for all • In this example, the client side submits a GET request for
content that is acceptable along with a a customer resource which your web API will try and send
relative quality factor (between 0 and 1). in JSON format, followed by XML and RSS.
• Your web API can send the same data in GET /customers/cust1
HTTP/1.1 200 OK Accept: application/json
various formats best suited to the API client … application/xml; q=0.8
environment. application/rss+xml; q=0.5
Considerations
API
• Be prepared for designing your web API so Web API
Consumer
that each format can be supported. Non-
alphanumeric characters can sometimes
throw off the formatting.

Return status codes for all requests in a way that is consistent
with the web
Status Code Returns Example:
• Each time a call is made to your web API, a
status should be returned so the caller HTTP/1.1 400 Bad Request
knows whether the result was successful or Content-Type: application/json
not. {
“errorcode”:”1234”,
“message”:”Incorrect request”,
How Status Code Return Works “docurl”:”http://mysite.com/errors/1234”
}
Example Description:
• There are well known HTTP response
• In this example, the client side submits a bad request
codes that should be passed after a
which your web API will capture and send an error status
response has been processed.
with additional details in JSON format.
• Provide an additional payload information to
assist developers who use your web API HTTP/1.1 400 Bad Request GET /customers/cust10
during development and troubleshooting. ... ...
Considerations
• Lack of industry consistency. Facebook, for API
Web API
example, returns only status code 200 with Consumer
error messages in the payload. Twilio provides
hyperlinks in their payload to aid in
troubleshooting.

Use generators and reuse existing web APIs if they already
exist
Use existing resources in the industry to accelerate development. Don’t waste time
developing commoditized components and libraries – focus your efforts on where you
can add business value.
Pre-Existing Web APIs

• Explore the web for existing web APIs in the industry that already provide the functionality you intend to offer.
Search through well known portals such as:
o APIs.io (search engine for APIs)
o ProgrammableWeb (community portal that includes a search engine for APIs and news)
o Google APIs Explorer (list of APIs for working inside Google’s ecosystem)
SDK & Pattern Generators

• These types of tools are use for wrapping your API into reusable components. Examples include:
o Swagger (includes client SDK generation, discoverability, and interactive documentation)
o RAML (a YAML-based modeling language for your web API)
Schema Generation Tools

• These types of tools enable sharing for portable JSON schemas with partners or an internal standard. Examples
include:
o JSON-Schema (a list of validators, generators, and parsers for various platforms and languages)
Generate documentation for your web APIs Train your team on proper design of APIs
• API Academy
• APIBlueprint
• Pluralsight

Phase 2 outline
Guided Implementation 2: Design and Develop a Web API

Proposed Time to Completion: 8 weeks
Phase 2: Design and Develop a Web API

• Identify the design and development gaps that need to be addressed.
• Review design and development practices outlined by Info-Tech.

2.1.2 Define high-level design details based on web API requirements.
2.1.3 Define your process workflows and business rules.
2.1.6 Identify the integration risks, security gaps, bottlenecks, and other risks in your data flow.
Design Requirements Template
Web API Design Document Template
Phase 2 Results:
• Understanding of best practices for design and development for web APIs.
• Web API design created.

Understand how your web API fits into your system architecture
2.1.1
The facilitator will walk you through the exercise of developing a high-level system
architecture to determine how your web API development project fits into your
business processes.
Define high-level design details based on web API requirements
2.1.2 Info-Tech will facilitate discussion around how the web API should be designed
based on requirements and use cases.
Define your process workflows and business rules
2.1.3 Info-Tech will facilitate discussion on the current state of your business process and
walk you through an exercise on mapping your business processes using process
workflow diagrams.

Map the relationships among data tables through ERDs
2.1.4 Info-Tech will facilitate discussion on the current state of your data and walk you
through an exercise on mapping your relationships between data sets using entity
relationship diagrams.
Document your web API data flow diagrams

2.1.5
Info-Tech will facilitate discussion around the current state of your data and walk
through an exercise on mapping your data model using data flow diagrams.
Identify the integration risks, security gaps, bottlenecks, and other

risks in your data flow
2.1.6 Info-Tech will facilitate discussion on drawing out risks associated with your data flow
for your API. The facilitator will also help you determine development practices to
minimize these risks.

Define your objects by effectively referencing your data model
2.1.7 The facilitator will walk through an exercise on how to create data collections
(objects) for web service exposure.

Phase
1 2 3 4
PHASE
Test the Web API 3
Phase 3: Test the web API
1 2 3 4
1 Examine the Opportunities 2.1 Design a Web API 4 Monitor & Continuously
2.2 Develop a Web API 3 Test the Web API
Recommended Timeline: 1 week
Info-Tech Insight • Understanding of best Deliverables from this Phase

Major practices for testing
Milestones web APIs.
Reached
There is no single test tool that can Web API Test
test all perspectives of a web API. Plan
Use specialized tools that can
• Generate test cases
effectively test different components Key using test design
of the API stack. Activities techniques.
Completed • Creation of web API
test plan.

Phase 3: Exercise Guide
There is no single test tool that can test all perspectives of a web API.
Use specialized tools that can effectively test different components of
the API stack.
flow.
3
Test the web API
Participants
Development Manager
Monitor and continuously optimize the web API Test Teams

Conduct testing for your web API when any level of the stack
changes
Initiate your web API testing around several types of changes. Lower level testing
should additionally trigger regression testing or higher level testing.
Code Changes Hierarchy of Web
API Testing
At the lowest level, we have code changes. Here the interface, schema, and call
sequence do not change. Emphasis on this type of testing is on ensuring the logic
of the API remains consistent after code refactoring, code deletion, or code Web API Orchestration
insertion.
Interface Changes Depends on
Every web API has an interface that is an agreed upon contract. Changing this
contract means testing for backward compatibility and performance. Changing the Schema
interface often means a change to the schema which should also be tested.
Interface design is difficult and you should expect to see this type of testing quite
frequently early in your API development. Depends on
Schema Changes
Interface
This could involve either addition, modification, or deletion of schema entities.
Emphasis should be placed on testing backward compatibility to ensure schema
changes do not affect marshalling and unmarshalling of parameters. Depends on
API Call Sequence Changes

Code
In some cases, a web API may call another web API on a different runtime.
Changes in orchestration will require testing the entire sequence. During this type
of testing, code changes may be necessary and therefore logic testing will be
needed as indicated above.

Place special emphasis on testing your web API for security
Plan for the worst-case scenario by developing test cases using the following security
test techniques.
Fuzzing Technique Malicious Content Technique
Use of random data to see whether your API crashes. Taking advantage of the API hosting infrastructure to
Data can either be generated randomly or using force a crash. Examples would be recursive objects that
modeling techniques to break the API using its original result in out of memory errors or passing corrupt binaries
intended usage. in the API call.
CON: Might have poor code
PRO: Bugs found using
coverage so it won’t
this approach can be PRO: Allows you to CON: You need to be
validate secure coding
severe and reveal prepare response teams careful not to bring down
practices and the focus
issues that are for such cases and to your entire system while
tends to centralize around
sometimes overlooked test incident response testing which could
boundary conditions to
even by experienced time. lengthen test cycle time.
avoid unbounded testing
testers.
time.
Invalid/Out-of-bounds Content Technique Injection Attacks Technique
Uses boundary conditions to test local and global Exploits the web API’s internal code syntax to execute
maxima and minima values, incorrect value types for with malicious intent. It could be at any stack level (SQL,
parameters, and incorrect HTTP headers. XSLT, JSON, JavaScript).
PRO: It is easy to CON: Any hard coded values PRO: Common attack
construct test cases could require maintenance CON: Requires code level
vectors are available
from well-defined as compilers continue to knowledge to create test
online so you have a
metadata during improve the range of values cases.
good starting point.
development. for data types.
Continually stay up to date on common security issues using well-known resources such as OWSAP, WS-
Attacks, and Zed Attack Proxy.
Expect to augment your legacy testing tools
When you test your web APIs today, look for certain key features in your testing tools.
HTTP
A GUI-based tool that allows you to simulate HTTP requests
HTTP Client with payload for both request and response.
Client
1 POST /blog/posts
2 ACCEPT: application/json ... Request Capture Ability to capture all incoming requests from API consumers.
From
DLC
Time Length Source Aimed at capturing all relevant inbound and outbound
I
Destination Protocol Summary
Traffic Capture HTTP/S network traffic to and from the API endpoint.
Exposing a developer’s local endpoint as a public URL that

Tunnel Local Tunneling other developers can share.
Development Tool Integration with common development tools like Eclipse and
Integration Visual Studio.
The ability to transform data from one format to another. For

ProxyTransformer Proxy Transform example, to different XML formats or from XML to HTML.
/api/login Authentication Allowing web API testing through proxy and authentication.
Ability to register and monitor results, hits, and transfer size

API Analytics metrics.
Step-by-Step Unit
Permits single step examination of requests and responses.
Testing

Consider using current web API testing and monitoring tools
Using a test suite can help with test case automation and integration with a continuous
integration suite. Realize what web API testing and monitoring tools are out there
before conducting custom in-house testing.
REST client based Local tunneling based Desktop/browser based
Hurl.it ngrok.com SoapUI

Postman Parasoft
Request capture based Monitoring/alert based Load testing tools
RequestBin Pingdom Apache JMeter

OpsGenie The Grinder
PaperDuty curl-loader
3scale
Traffic capture/HTTP Acceptance/

Test data/mocks based
sniffers Specification based
Fiddler json-generator Fitnesse
Charles Mocky Cucumber/SpecFlow
HTTPScoop
Wireshark Javascript/node based
Frisby

Merge web API test cases into continuous integration activities
The eventual goal of test case creation should be insertion into a continuous
integration suite of cases for automation.
• In the long term, your web API testing will lend itself well to automated testing because your web API interface will
eventually be stable and test case execution will be repeatable.
• Start with manual testing and eventually integrate your often repeated test cases into a CI tool to form a robust regression
suite.
1 Create your testing from test types 2 Create your test cases
• Security testing: Focus on metrics around authentication,
endpoint certificate security, caching/session replay, and • Model based: Use finite state machines, symbolic
modification to data in transit. execution, and theorem proving to drive out test
• Load testing: Look at performance metrics like response time cases.
per call and number/type of API exception errors returned. • Synthetic based: If your API is orchestrated,
• Usability testing: From a design perspective, look at create test cases based on the way you know your
consistency of your API signatures and call methodology. API is being consumed by most developers.
• Anti-fragility testing: Test for graceful degradation cases, • Scenario based: Using a use case or functional
default responses, and time to recover from faults or failures. approach, define the scenario in a “Given, When,
• Error testing: Ensure the correct error codes and Then” syntax.
descriptions are returned.
API testing is not the same as testing through an application GUI. Application functional testing tends
to be black box and can mask logic and performance errors that white box API testing reveals. In some
cases, it may not be possible to conduct testing for legacy APIs – either the code is no longer available or
API testing might be expensive. In such cases, performing functional regression testing is a reasonable
alternative compared to not testing at all.

Create test cases using model, synthetic, and scenario-based
test design techniques
Model Based Testing (MBT) Synthetic Based Testing Scenario Based Testing
Description Description Description

The software under test can be under This technique is demonstrated in the Scenario based testing is creating test
situation, which are called states. The form of flow diagrams in which each cases from use cases of your system
transition which denotes going from flow represents a common use of your under test (or user stories in Agile
one state to another are the test web API. Synthetic based testing is environments). These use cases
cases generated from this test design effective under low payload conditions usually originate from your business,
technique. in which errors can be traced back to functional, and non-functional
source code defects in synthetic requirements. Test cases are
based test tools. generated from denoting use cases in
a “If. Then. When.” syntax.
Steps Steps Steps
1. Determine the different states of 1. Determine the most common ways 1. Determine all scenarios of how
your web API. your web API is used. Represent your web API can be used (if use
2. Generate test cases by these in flow diagrams. cases/user stories have been
determining how to go from one 2. The flows created in step 1 are to already developed, use these).
state to another. be tested end to end. 2. Determine scenarios of how each
use case will be proceed in a “If.
Then. When.” syntax template.
Model Based Testing Example Synthetic Based Testing Example Scenario Based Testing Example
STATE 2: Username  USE CASE 1:
SUCCESSFUL Password  API User requests USER AUTHENTICATION
LOGIN User
FLOW 1 authenti GET
logs in
Username  STATE 3: -cates /customers… IF: API consumer tries to authenticate;
Password  INCORRECT THEN: return success code 200;
STATE 1: LOGIN WHEN: the credential exists in AD.
API does API
NOT LOGGED User
Username  Username  FLOW 2 not responds to
IN logs in
authenticate user…
Password  Password 

Exercise: Create test cases using model, synthetic, and
scenario-based test design techniques
3.1 2 Hours
Instructions INPUT
1. Determine the test type that you will create test cases for (e.g. performance, load,
usability). • Previous testing
experiences and
2. Determine which test design techniques will be used to generate test cases (model,
documentation
synthetic, or scenario based).
Model-based Testing:
1. Determine the different states of your web API. Use sticky notes to document the various OUTPUT
states and place them on the whiteboard.
2. Generate test cases by determining how to go from one state to another. Use markers to • Web API test cases
draw lines to illustrate state transitions.
Synthetic-based Testing:
3. Determine the most common ways your web API is used. Represent these in flow diagrams.
Use sticky notes to document each component of a flow. Materials
Scenario-based Testing:
4. Determine all scenarios of how your web API can be used (if use cases/user stories have • Whiteboard and
been already developed, use these). markers
5. Determine scenarios of how each use case will be proceed in a “If. Then. When.” syntax • Sticky notes
template. Use sticky notes to document each scenario in the “If. Then. When.” syntax
template. Participants
Synthetic-Based Testing Scenario-Based Testing
Model-Based Testing Example
Example Example
• Development
Manager
Transition
Action IF: …..
• Test Teams
COMP- COMP-
FLOW THEN: …..
STATE STATE ONENT ONENT
1 WHEN: …..
1 2 1 2

Exercise: Create a test plan for your web API
3.2 1 Hour
• A test plan specifically for your web API provides guidance on testing activities required. INPUT
The test plan forces testers to confront what test activities take priority based on time and
resource constraints. • Previous testing
• Communicate with members of the project team and other test stakeholders the scope of experiences and
testing and realistically determine what can and cannot be tested. documentation
Instructions OUTPUT
1. Define your test approach by defining what features are to be tested and not to be tested. • Web API test plan
2. Determine what test types will be conducted for your web API (e.g. payload testing).
Determine what test design techniques are to be used for each test type to determine test
cases (e.g. malicious content). Define roles and responsibilities associated with each test
type. Materials
3. Determine what tools and test environment requirements are necessary for your web API • Whiteboard and
testing activities. markers
4. Identify the high-risk assumptions of your test plan. Specify contingency plans for each • Web API Test Plan
(e.g. delay in delivery of test items might require increased night shift scheduling to meet Template
delivery date).
Participants
5. Document steps 1 through 4 in the Web API Test Plan Template.
• Development
Manager
A tester’s definition of risk relates to the likelihood of a defect occurring, whereas • Test Teams
the business sees risk from a feature prioritization perspective. It is important to
ensure the business has sufficient information to make a decision regarding risk
to the organization.

CASE STUDY Publicly-held company increases revenues by
Organization incorporating proper testing specifications for API
Anonymous
Industry Establish Test Test Results Automated

Unknown Specifications Analytics Testing
Key Business Benefits

• Increased number of defects found.
• Increased API performance throughput
and response time using analytics.
e: gic • Development and testing time is
o urc tyLo
S ali reduced.
Qu
• Anonymous business wanted to embark

• QualityLogic worked closely with the • Nearly 200 bugs were found.
on an initiative to increase revenue by
organization’s development team to • Web API passed every functional test
making its quality interactive services
develop a formal test specification case and met all outlined specifications.
product available on the web via APIs.
detailing features of test customers and • Monitoring initiatives post-deployment
• The API under development was a REST
more than 300 tests cases to validate revealed a variety of issues that helped
web services interface exposed to a
appropriate API behavior. tune the performance of the API to
customer account management system
• QualityLogic created automated test meet throughput and response time
which provided various web properties.
cases with over 2,000 API calls and 2,500 goals.
• Development approach was not well
test assertions to confirm appropriate API • Development and testing times were
defined or executed. The business
behavior. decreased with significant increases
lacked documentation and operated with
• Over the course of the project, load and made to specification documents for the
poor test specifications and disorganized
scalability tests were conducted. API.
test environments.

Phase 3 outline
Guided Implementation 3: Test the Web API

Phase 3: Test the Web API

• Review current testing practices.
• Discuss how to create test cases using certain test design techniques.
• Determine what testing practices specifically for web APIs need to incorporated in current testing activities.
• Discuss what components need to be included in your web API test plan.


Web API Test Plan Template
Phase 3 Results:
• Understanding of the different techniques to generate effective test cases.
• A comprehensive test plan for web APIs is developed.

Create test cases using model, synthetic, and scenario-based test

3.1 design techniques
Info-Tech will walk you through an exercise of creating test cases using the three test
design techniques outlined in this activity.
Create a test plan for your web API

Info-Tech will facilitate discussion how to create a test plan for your web API. These
3.2 discussions surround topics such as the overall test approach and test design
techniques for test case creation, and high-level risks associated with your testing
activities.

Phase
1 2 3 4
PHASE
Monitor & Continuously Optimize the Web API 4
Phase 4: Monitor and continuously optimize the web API
1 2 3 4
1 Examine the Opportunities 2.1 Design a Web API 3 Test the Web API
Web APIs Can Enable
4 Monitor & Continuously
Optimize the Web API
Recommended Timeline: Ongoing
Info-Tech Insight • Gaps in IT capabilities Deliverables from this Phase

Major and business needs
Milestones are made known and
Reached Web API Process
are to be addressed.
Governance
• Understanding of
Template
API management is an ongoing versioning
effort, not a one-time event. approaches.
• Processes created for

Key
Activities managing web APIs
Completed from business and IT
outlooks.
Phase 4: Exercise Guide
API management is an ongoing effort, not a one-time event.

flow.
3
Test the web API
Participants
Development Manager
Monitor and continuously optimize the web API IT Director

Expect usage to go beyond your original intent
Relevant use cases of your web API come to fruition when API consumers use it. Plan
web API evolution iteratively in order to accommodate for these use cases.
In order to address you not knowing how your customers are going The hard part is that you have no idea how
to use your API, one technique to build or modify that data that we customers are going to use your API…Build
use for regression testing is to have some sort of diagnostic or way that minimum step for the initial
of tracking how customers are calling your API. Even if your deployment that lets your users do
customers are trying to call your API and are failing, you can still something, and let them iterate on that.
get some learning from that too. You collect that data and use that Observe what else they think they need, and
data to help API development as well as new test support. then add more features and go from there.
– Alan Page, Principal Software Engineer at – Alan Page, Principal Software Engineer at
Microsoft Microsoft
Monitor your web API usage patterns as a starting point for Continuous API Documentation
updates made to your web API. Provide developers with an API • Be clear in your documentation your API’s intent and usage
change log to see how the API has evolved over time. Provide to avoid API consumers from making assumptions that are
changes via release notes to provide API consumers with an invalid.
understanding of how the changes may affect their application.
• Take a well-balanced approach to documentation. If the
• RUM (Real User Monitoring) can be used to determine web API requires an API consumer to fully understand the
bandwidth and runtime platforms so you can optimize for those use of your web API, then you don’t have an optimal API
scenarios. design. The core functionality of your API should be intuitive
– include examples of advanced API features.
• Synthetic monitoring can be used to call your commonly used • Your web API has to evolve in order to remain relevant.
web API orchestrations to determine whether any error Managing this change through documentation and
conditions exist under low load conditions. versioning is critical. Keep your web API documentation up
to date. Tools like Mashery, Swagger, and APIBlueprint
Source: Lawton, George. “API World Conference reveals API developer pain can do this for you in an automated fashion.
points”.

Manage your web API for versioning and compatibility
Aim to version your web API for backwards compatibility; use a versioning approach
that enables this.
Request changes that are considered backwards Request changes that are not considered backwards
compatible: compatible:
• Adding endpoints. • Adding a new mandatory field to the request interface.
• Adding operations to an existing endpoint. • Making a previously optional field in the request
• Adding optional fields to the request interface. mandatory.
• Changing a mandatory field to optional in an existing • Removing fields from the request or the response.
request interface. • Making a previously required response field optional.
• Adding fields to a response. • Changing the relationship between fields.
Versioning Approaches: Source: Biske, Todd. “Get a grip! How to handle API versioning decisions”. TechTarget. 2014.
URI
URI Path api.myuri.com/v2/user/... api.myuri.com/users/12345?v=1.2
Parameter
• Adding a new parameter in your URI that indicates • Addition of a query string parameter to indicate version
the version. required.
• PRO: Distinct URIs make backward compatibility easy. • PRO: Consumers can choose which version they want to use; each
• CON: Have to manage multiple versions of the same version is stable.
URI. • CON: If consumers use the latest version, they may be surprised by
Content Accept: image/jpeg unintended
Custom changes.
Negotiation image/gif; q=0.8 Request Header
• Uses HTTP headers to determine version. • Adds a custom attribute in the HTTP header.
• PRO: Consumers don’t have to change at their end • PRO: Consumers don’t have to change at their end because
because versioning is removed from the URI. versioning is removed from the URI.
• CON: Additional complexity, HTTP header support is • CON: Additional complexity since versioning is not highly visible.
not universal.
Source: Musser, John. “What Makes a Great Open API?”. OSCON2012. 2012.
Establish a governance model for managing your web API
Prior to deployment, establish two governance structures. Without it, an unmanaged

web API could result in confusion and fragmentation at best.
Establish an IT Service Governance Model Establish a Web API Process Governance Model
What It Means: What It Means:
• Instill processes that ensure effective and efficient • Development and implementation processes that
use of IT in enabling the appropriate use of the web execute the IT Service Governance Model for your
API. web API.
Items to Address: Items to Address:
 Identify the actors responsible for offering services to  Identify the actors in the architecture, development,
the business that make use of the web API. and support of your web API.
 Note the specific business or partnership SLAs  Articulate the process that represents the normal
agreed upon. day-to-day operations for architecture, development,
 Determine who should be responsible for decisions and support under non-error conditions.
around changes to the web API (versioning, API  Determine what should be done under less than
deprecation policy). ideal conditions for each of architecture,
 Determine the ownership of any third-party vendor development, and support.
management.
As part of your API versioning strategy, you also need a deprecation policy. The
reality is that most new APIs today have a versioning strategy, but very few also
come out of the gate with a deprecation policy. Your policy should explicitly state
how long you will support each version of your API given some degree of notice.
– John Musser, Founder & CEO at API Science.

Exercise: Identify roles for your API development projects
4.1 0.5 Hours
• IT executes a number of processes to serve business needs. These processes need be INPUT
assigned to certain individuals that are part of the web API development team.
• From an optimization perspective, IT drivers help act as high-level acceptance criteria for • Business drivers
process changes within IT. It is important to understand how IT can help support business • IT capabilities
needs and what processes need to be established to enable web API development.
Instructions OUTPUT
• Identified IT
1. Identify the actors in the architecture, development, and support of your web API
governance gaps
development projects. Determine the responsibilities for each actor in a given web API
development initiative.
2. Use the Web API Process Governance Template to document your RACI table.
Materials
Project-Specific Responsibilities
• Whiteboard and
Development Accountable for quality assurance and managing testing initiatives conducted
markers
Manager by test teams.
• Web API Process
Responsible for setting up the infrastructure and ensuring proper installation Governance
IT Operations
and availability of the test tools. Template
Responsible for providing high-level guidance on the flow of data across
Data Architect
systems to ensure integration works as expected.
Participants
Responsible for conducting testing for web APIs during development and prior • Development
Tester to deployment; consulted to provide insights on test approach deemed most Manager
suited for web APIs. • IT Director
Accountable for ensuring a high value, widely available, and sustainable
IT Director
mobile platform from design to deployment.

Exercise: Develop governance for web API development
4.2 1 Hour
• You need to establish a governance structure around how to execute web API activities, INPUT
and it should be enforced by management to direct the project succession.
• Having a set web API process will ensure accountability among involved stakeholders, and • IT capabilities
help them understand what is required at critical points in the development process.
Instructions OUTPUT
1. Based on the roles and responsibilities identified in exercise 4.1, articulate processes that • Web API
represent normal day-to-day operations for each of the architecture, development, testing, development process
and support groups under non-error conditions. Create a process flow to include sunny flow
day as well as rainy day scenarios (situations where the process is not operating as
expected). Materials
2. Determine what should be done under less than ideal conditions for architecture,
• Whiteboard and
development, testing, and support steps. Determine a reporting structure around having a
markers
clear approval and escalation process to promptly notify stakeholders of discrepancies and • Web API Process
quickly push process fixes in rainy day scenarios. Governance
Template
Participants
• Development
Manager
• IT Director

Exercise: Measure the value of your web API project
4.3 1 Hour
Instructions INPUT
1. Based on the metrics established in Exercise 1.1, determine the effectiveness of your • Metrics from Exercise
web APIs by documenting the measurements for each metric used to measure the web 1.1
API development project. • Satisfaction survey
2. Conduct a results survey of business users which use the applications exposed to the results
web API developed. Determine the satisfaction rating of each application to gauge the OUTPUT
value of your web API.
3. Based on your measured value and survey evaluations, determine what new • Documented web API
functionalities can be added to web API to further enhance application experiences. results
• Considerations for
Business Metric Measurement Application Satisfaction Satisfaction new web API features
Objective exposed to rating before rating after
web API Materials
Improve Number of calls to Average 100 CRM 1 out of 5 5 out of 5
customer web API which calls/hour • Whiteboard and
retention supports customer markers
marketing
Improve Number of calls to Average 500 HR Payroll 3 out of 5 4 out of 5

service web API which calls/hour Participants
experience provides customer
data • Development
SMMP 3 out of 5 3.5 out of 5 Manager
Optimize field Number of calls to Average 5
• IT Director
service web API which calls/hour
productivity provides data to
remote users

Manage the full lifecycle for your web API
Once your web API is released into production, you need to include onboarding,
monitoring, and future enhancements in your future plan.
Once your web API is in production, you need to focus on three key areas:
Monitor Usage, API Integration
1 Business Engagement 2 Reporting, & Analytics 3 Roadmap
• Have an onboarding plan for new • Questions to consider when • For managing the roadmap
teams or business partners to looking into monitoring and integration for purchased APIs,
consume your API. Some reporting initiatives: consider the following questions:
questions to consider are: o Is the load across all callers o In cases where you did not
o How will they be supported? consistent or are there outliers create the API, how will
(Think about both process and that may be affecting overall backward compatibility be
structure.) performance? assured?
o Who will handle infrastructure o Are there certain times where o What is the roadmap of the
issues like key management? API usage is higher? web API owner?
o Can they recommend API o Are there patterns where API
changes? consumers are not properly
o Will you offer some type of calling your web API? What
SLA? What happens in a can you learn from this?
breach? o Will web API consumers have
o Are there any security or access to reports? If so, which
compliance requirements for ones?
external business partners? o Can API consumers give
feedback on functionality?
An API management tool can help with most of these focus points stated above. Some leading vendors in this
space are: Apigee (Edge), IBM (IBM API Management), Intel (Mashery), and Microsoft (Azure API
Management).

Phase 4 outline
Guided Implementation 4: Monitor and continuously optimize your web API

Phase 4: Monitor and continuously optimize your web API

• Review current governance practices for development projects.
• Identify the IT capabilities gaps outlined by the business that need to be addressed.
• Determine how business and IT can collaborate on managing web APIs effectively.
• Discuss measured value of web API development project and determine potential functionalities to include in
the next web API development iteration.

4.1 Identify IT governance gaps that need to be addressed for your web API development project.
4.2 Develop a governance structure for web API processes.

Web API IT and Process Governance Template
Phase 4 Results:
• Processes created for managing web APIs from business and IT perspectives.
• Web API development project measured and potential new functionalities made known for the next iteration.

Identify IT governance gaps that need to be addressed for your web

API development project
4.1
Info-Tech will facilitate a discussion on what your IT department offers for supporting
development projects and what your business needs are. These discussions will lead
to an agreement on where resources should be allocated for meeting business goals
and objectives.
Develop a governance structure for web API processes

Info-Tech will walk through the steps to develop an appropriate process for
4.2 management of web API development activities. A process flow for web API
execution will be generated.
Measure the value of your web API project

Info-Tech will walk through steps on assessing the value of your web API
4.3 development project.

Research Contributors and Experts
Alan Page
Principal Software Engineer
Microsoft
Alan Page has been a software tester for nearly 20 years. He was the lead author on the book How We Test
Software at Microsoft, contributed chapters for Beautiful Testing and Experiences of Test Automation: Case
Studies of Software Test Automation , and recently published a collection of essays on test automation in The
A Word. He also writes about a variety of software engineering subjects on his blog at http://
angryweasel.com/blog. Alan joined Microsoft as a member of the Windows 95 team, and since then has
worked on a variety of Windows releases, early versions of Internet Explorer, and Office Lync and Xbox One.
Alan also served for two years as Microsoft’s Director of Test Excellence.
Ken Toole
Senior Director of Engineering, Platform Technology &
Services
Adobe Systems
As senior director, Ken is responsible for the day to day engineering effort required to deliver core pieces of
Adobe’s online business infrastructure supporting all of Adobe’s online services and product offerings.
Toole’s work includes the development, quality, and engineering operations of a wide array of hosted services
at the infrastructure and e-commerce level, consumer facing web applications and desktop components
embedded in Adobe’s industry leading desktop applications. His other responsibilities include contributing to
Adobe’s strategy and technology deliveries to support 3rd party developers and our large enterprise
customers that rely on Adobe’s creative products to drive their businesses. Toole’s engineering team is
spread between the U.K., India, and the United States.

Research Contributors and Experts
Ed Anuff
VP, Product Strategy
Apigee
Ed Anuff is a respected technologist and a proven innovator with over 20 years of experience as an
entrepreneur. In 2010, he founded Usergrid, a startup that created a mobile backend-as-a-service (BaaS) to
provide cloud services for powering mobile and rich client applications. Usergrid was acquired by Apigee in
2012. Prior to starting Usergrid, he was most recently Executive VP and General Manager of Six Apart, which
is known for creating the Movable Type blogging platform, TypePad blogging service and Vox social network.
He was co-founder of Widgetbox, a popular marketplace for widgets, and he was also co-founder of
enterprise software company Epicentric, a provider of enterprise portal software. Anuff was also responsible
for the launch of HotBot, one of the first large-scale web search engines, when he was an executive at Wired.
John Musser
Founder & CEO
API Science
John Musser is CEO of API Science and previously founded ProgrammableWeb, the leading online resource
on open APIs. John is an industry expert on APIs, quoted in the Wall Street Journal, New York Times, Forbes,
and Wired, and speaking at conferences including SXSW, Dreamforce, and Web 2.0. He also consults on
API strategy and trends with clients including Google, Microsoft, and Salesforce. Find him on twitter at
@johnmusser.

Appendix - Bibliography
Anonymous. “Building Reusable APIs in a Mobile First, Cloud First Business Environment: Technical Case Study”. Microsoft.
Feb. 2015. Web. Feb. 2015. https://msdn.microsoft.com/en-us/library/dn922163.aspx.
Anonymous. “FedEx shipping API is down, causing Shipping Service to be unavailable and causing slow response to
Storefronts”. Incident Report for Bigcommerce. 17 Jan. 2015. Web. Feb. 2015.
http://status.bigcommerce.com/incidents/4q1qm9lcxh94.
Anonymous. “Google API infrastructure outage incident report”. Google Developers Blog. 3 May 2013. Web. Feb. 2015.
http://googledevelopers.blogspot.ca/2013/05/google-api-infrastructure-outage_3.html.
Anonymous. “Model-Based Testing”. Microsoft. 2015. Web. Feb. 2015.
https://msdn.microsoft.com/en-us/library/ee620469.aspx.
Anonymous. “Top 10 2013 Security Threats”. OWASP. 2013. Web. Feb. 2015.
https://www.owasp.org/index.php/Top_10_2013-Top_10.
Anonymous. “Wine API success for commercial purposes”. 3scale. 2015. Web. Feb. 2015.
http://www.3scale.net/wp-content/uploads/2015/03/API-Use-Case-Wine.com_.pdf.
Biske, Todd. “Get a grip! How to handle API versioning decisions”. TechTarget. Dec. 2014. Web. Feb. 2015.
http://searchsoa.techtarget.com/tip/Get-a-grip-How-to-handle-API-versioning-decisions.
Bloch, Joshua. “How to Design a Good API and Why It Matters”. Google TechTalks. 2007. Web. Feb. 2015.
http://lcsd05.cs.tamu.edu/slides/keynote.pdf.
Boyd. Mark. “6 Business Benefits of Private APIs”. Nordic APIs Blog. 13 Feb. 2014. Web. Feb. 2015.
http://nordicapis.com/business-benefits-of-private-apis/.
Crocker, Peter. “Mobile Apps in the API Economy: Avoiding the Mobile Cliff.” Smith’s Point Analytics. Aug. 2013. Web. Feb.
2015. http://www.smithspointanalytics.com/Mobile-Apps-in-the-API-Economy.pdf.
Dhall, Chander. “5 Best Practices for Better RESTful API development”. 17 Oct. 2013. Web. Feb. 2015.
http://devproconnections.com/web-development/restful-api-development-best-practices

DuVander, Adam. “API Consumers want reliability, documentation, and community”. ProgrammableWeb. 7 Jan. 2013. Web.
Feb. 2015.
http://www.programmableweb.com/news/api-consumers-want-reliability-documentation-and-community/2013/01/07 .
Fern et al. “Web API Study: The Benefits of APIs in the App Economy.” Hurwitz & Associates. 2011. Web. Feb. 2015.
http://hurwitz.com/recent-research/item/web-api-study-the-benefits-of-apis-in-the-app-economy.
Gat, Israel, and Giancarlo Succi. “Agile Product & Project Management Executive Update Vol. 14, No. 6: A Survey of the API
Economy.” Cutter Consortium. 2013. Web. Feb. 2015.
http://www.cutter.com/content-and-analysis/resource-centers/agile-project-management/sample-our-research/apmu1306/ap
mu1306.pdf
.
Giza, Maxine. “Innovative, practical API design captures travel-lover’s imagination”. TechTarget. Nov. 2014. Web. Feb. 2015.
http://searchsoa.techtarget.com/feature/Innovative-practical-API-design-captures-travel-lovers-imagination .
Hague, Promod. “Businesses must embrace the programmable world. Or die.” Fortune.com. Sept. 2013. Web. Feb. 2015.
http://fortune.com/2013/10/22/businesses-must-embrace-the-programmable-world-or-die/ .
Jansen, Geert. “The Job of the API Designer.” RESTful API Design. 2011. Web. Feb. 2015.
http://restful-api-design.readthedocs.org/en/latest/scope.html.
Jauker, Stefan. “10 Best Practices for Better RESTful API”. m-way solutions. 5 June 2015. Web. Feb. 2015.
http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/.
Johnson, Tom. “API doc survey: Most challenging aspect of API documentation”. I’d Rather Be Writing. 12 Jan. 2015. Web.
Feb. 2015. http://idratherbewriting.com/2015/01/12/api-doc-survey-most-challenging-aspect-of-api-documentation/ .
Lawton, George. “API World Conference reveals API developer pain points”. TechTarget SearchSoftwareQuality. 22 Sept.
2014. Web. Feb. 2015.
http://searchsoftwarequality.techtarget.com/news/2240231187/API-World-Conference-reveals-API-developer-pain-points .
Moore, Alan and Dinesh Shetty. “Recommended Practices for Designing a Web API”. IBM Impact 2013. 10 May 2013. Web.
Feb. 2015. http://www.slideshare.net/ibmapimgmt/recommended-practices-for-designing-a-web-api.
Musser, John. “API Business Models.” API Strategy Conference. 2013. Web. Feb. 2015.
https://www.youtube.com/watch?v=gfguGS8HYvM.
Musser, John. “What Makes a Great Open API?”. OSCON2012. 18 July 2012. Web. Feb. 2015.
http://www.slideshare.net/jmusser/what-makes-a-great-open-api.
Nolle, Tom. “API security more critical as componentization grows”. TechTarget. Dec. 2014. Web. Feb. 2015.
http://searchsoa.techtarget.com/tip/API-security-more-critical-as-componentization-grows.
Pedro, Bruno. “5 Ways APIs will Increase your Revenue”. Nordic APIs Blog. 27 Aug. 2014. Web. Feb. 2015.
http://nordicapis.com/5-ways-apis-will-increase-revenue/.
Pedro, Bruno. “How to Monetize your API”. Nordic APIs Blog. 1 Sept. 2014. Web. Feb. 2015.
http://nordicapis.com/how-to-monotize-your-api/.
Plamondon, Jim. “Introducing the API Economy: A Dialogue.” Cutter Consortium Agile Product & Project Management
Executive Report, Vol. 12, No. 8. 2012. Web. Feb. 2015.
http://www.cutter.com/content-and-analysis/resource-centers/agile-project-management/sample-our-research/apmr1208/apm
r1208.pdf
.
Sahni, Vinay. “Best Practices for Designing a Pragmatic RESTful API”. VinaySahni. Web. Feb. 2015.
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#docs.
Spencer, Travis and Jennifer Riggins. “APIs Power the Internet of Things”. Nordic APIs Blog. 5 Jan. 2015. Web. Feb. 2015.
http://nordicapis.com/apis-power-the-internet-of-things/.
Stafford, Jan. “How to handle challenges with API security and efficiency”. TechTarget. Mar. 2014. Web. Feb. 2015.
http://searchsoa.techtarget.com/feature/How-to-handle-challenges-with-API-security-and-efficiency .
Stafford, Jan. “Q&A: How to reduce API security threats, use Oauth, provision API keys”. TechTarget. Dec. 2014. Web. Feb.
2015. http://searchsoa.techtarget.com/feature/QA-How-to-reduce-API-security-threats-use-OAuth-provision-API-keys .

Stowe, Mike. “New Series: API Design Best Practices”. MuleSoft Blog. 6 Nov. 2014. Web. Feb. 2015.
http://blogs.mulesoft.org/api-best-practices-series-intro/.
Takahashi, Dean. “The new dial tone: How the API economy accelerates the growth of cloud apps.” The API economy panel
at CloudBeat. Sept. 2013 Web. Feb. 2015.
http://venturebeat.com/2013/09/09/the-new-dial-tone-how-the-api-economy-accelerates-the-growth-of-cloud-apps/ .
Willmott, Steve. “The Five Axioms of the API Economy, Axiom #4 – Organizations must provide core competence through
APIs.” 3scale. Sept. 2014. Web. Feb. 2015. http://www.3scale.net/2014/05/five-axioms-of-the-api-economy-axiom-4/.

02 Develop APIs That Work Properly For The Organization Phases 1 4

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

02 Develop APIs That Work Properly For The Organization Phases 1 4

Uploaded by

Copyright:

Available Formats

Develop APIs That Work Properly for the

This Research Is Designed For: This Research Will Help You:

Outcomes of this Research:

Info-Tech Research Group 2

Situation ! Info-Tech Insight

Info-Tech Research Group 3

Info-Tech Research Group 4

Module 1: Module 2: Module 3: Module 4:

Info-Tech Research Group 5

Contact your account representative or email Workshops@InfoTech.com for more information.

Workshop Day Workshop Day Workshop Day

Info-Tech Research Group 6

Info-Tech Research Group 7

Recommended Timeline: 1 week

Info-Tech Research Group 9

Info-Tech Research Group 10

Process Orchestration Architectural Components

Business that operates over a network.

Internal Web APIs

Users • ESB – a software architecture model

Business • Process Orchestration – management

Partners Data of multi-interaction processes across

Your Organizational Needs

Info-Tech Research Group 12

Info-Tech Research Group 14

RUNTIME ISSUES Indicators of a Poor Web API

Info-Tech Research Group 15

Adopting an API-enabled application ecosystem enables your

Info-Tech Research Group 16

Consider the possibility that your internal services can be

Pay As You Go Tiered Pricing Freemium In order to monetize

Applicable API Use Cases

Situation Solution Results

Info-Tech Research Group 18

Applicable API Use Cases

Situation Solution Goals and Results

• Walgreens realized that the • Walgreens began offering its

Info-Tech Research Group 19

Applicable API Use Cases

Situation Solution Results

• Microsoft CEO announced its drive • Microsoft developed an API-centric

Info-Tech Research Group 20

Info-Tech Research Group 21

Metric Type Metric Business Objective

Developers Total developers using API

Info-Tech Research Group 22

1. Improve customer retention Send out promotions

Info-Tech Research Group 23

STEP 1 Re/Design STEP 2:Develop

external layout Caching

STEP 4 Monitor STEP 3:Test

Info-Tech Research Group 24

Leverage Info-Tech’s repeatable development process to improve the

Design & develop a web API

Monitor and continuously optimize the web API

Info-Tech Research Group 25

Guided Implementation 1: Examine the Opportunities Web APIs Can Enable

Phase 1: Examine the Opportunities Web APIs Can Enable

Then complete these activities…

With these tools & templates:

Info-Tech Research Group 26

Info-Tech Research Group 27

2.2 Develop a Web API