PHASE 4

Monitor and Continuously Optimize the Web

API

Develop APIs That Work Properly for the Organization

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
Phase

1 2 3 4
PHASE
Monitor & Continuously Optimize the Web API 4
#
Info-Tech Research Group 2
Phase 4: Monitor and continuously optimize the web API
1 2
1 Examine the Opportunities
Web APIs Can Enable
Recommended Timeline: Ongoing
Info-Tech Insight
API management is an ongoing
effort, not a one-time event.
3 4
2.1 Design a Web API 3 Test the Web API
4 Monitor & Continuously
2.2 Develop a Web API
Optimize the Web API
• 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
versioning
approaches.
• Processes created for
Key
Activities managing web APIs
Completed from business and IT
outlooks.
Info-Tech Research Group 3
Phase 4: Exercise Guide

API management is an ongoing effort, not a one-time event.

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
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
Development Manager
Monitor and continuously optimize the web API IT Director
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.

Info-Tech Research Group 4

 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
to use your API, one technique to build or modify that data that we
use for regression testing is to have some sort of diagnostic or way
of tracking how customers are calling your API. Even if your
customers are trying to call your API and are failing, you can still
get some learning from that too. You collect that data and use that
data to help API development as well as new test support.
– Alan Page, Principal Software Engineer at
Microsoft
Monitor your web API usage patterns as a starting point for
updates made to your web API. Provide developers with an API
change log to see how the API has evolved over time. Provide
changes via release notes to provide API consumers with an
understanding of how the changes may affect their application.
• RUM (Real User Monitoring) can be used to determine
bandwidth and runtime platforms so you can optimize for those
scenarios.
• Synthetic monitoring can be used to call your commonly used
web API orchestrations to determine whether any error
conditions exist under low load conditions.
Source: Lawton, George. “API World Conference reveals API developer pain
points”.
The hard part is that you have no idea how
customers are going to use your API…Build
that minimum step for the initial
deployment that lets your users do
something, and let them iterate on that.
Observe what else they think they need, and
then add more features and go from there.
– Alan Page, Principal Software Engineer at
Microsoft
Continuous API Documentation
• Be clear in your documentation your API’s intent and usage
to avoid API consumers from making assumptions that are
invalid.
• Take a well-balanced approach to documentation. If the
web API requires an API consumer to fully understand the
use of your web API, then you don’t have an optimal API
design. The core functionality of your API should be intuitive
– include examples of advanced API features.
• Your web API has to evolve in order to remain relevant.
Managing this change through documentation and
versioning is critical. Keep your web API documentation up
to date. Tools like Mashery, Swagger, and APIBlueprint
can do this for you in an automated fashion.
Info-Tech Research Group 5
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
compatible:
• Adding endpoints.
• Adding operations to an existing endpoint.
• Adding optional fields to the request interface.
• Changing a mandatory field to optional in an existing
request interface.
• Adding fields to a response.
Request changes that are not considered backwards
compatible:
• Adding a new mandatory field to the request interface.
• Making a previously optional field in the request
mandatory.
• Removing fields from the request or the response.
• Making a previously required response field optional.
• 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.
X-HTTP-Method-Override: PUT
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.
Info-Tech Research Group 6
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
What It Means:
• Instill processes that ensure effective and efficient
use of IT in enabling the appropriate use of the web
API.
Items to Address:
 Identify the actors responsible for offering services to
the business that make use of the web API.
 Note the specific business or partnership SLAs
agreed upon.
 Determine who should be responsible for decisions
around changes to the web API (versioning, API
deprecation policy).
 Determine the ownership of any third-party vendor
management.
Establish a Web API Process Governance Model
What It Means:
• Development and implementation processes that
execute the IT Service Governance Model for your
web API.
Items to Address:
 Identify the actors in the architecture, development,
and support of your web API.
 Articulate the process that represents the normal
day-to-day operations for architecture, development,
and support under non-error conditions.
 Determine what should be done under less than
ideal conditions for each of architecture,
development, and support.

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.

Info-Tech Research Group 7

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.

Info-Tech Research Group 8

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

Info-Tech Research Group 9

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

Info-Tech Research Group 10

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).

Info-Tech Research Group 11

Phase 4 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 4: Monitor and continuously optimize your web API

Proposed Time to Completion: 4 weeks

Phase 4: Monitor and continuously optimize your web API

Start with an analyst kick off call:
• 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.

Then complete these activities…

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.
4.3 Measure the value of your web API project.

With these tools & templates:

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.

Info-Tech Research Group 12

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

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.

Info-Tech Research Group 13

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.

Info-Tech Research Group 14

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.

Info-Tech Research Group 15

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

Info-Tech Research Group 16

Appendix - Bibliography

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.
Info-Tech Research Group 17
Appendix - Bibliography

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 .

Info-Tech Research Group 18

Appendix - Bibliography

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/.

Info-Tech Research Group 19