TIBCO Success Guide

Success Guide for the

API Product Manager
Creating an API program that
delights developers and grows
digital business

The Shifting API Landscape

Early on, APIs were heralded as a means to rapidly adapt
to shifting customer demand for omni-channel access to an
organization’s online information. As consumers moved from
desktops to laptops to mobile phones and tablets, companies
that did not adopt an API program were left scrambling. The
best companies seemed to be those who took their programs
a step further and opened their APIs to third-party developers
and built an API ecosystem.
The API market has evolved dramatically. Many of the
bellweathers of the open API ecosystem have pulled their
programs back from open access or severely limited the
amount of data publicly available. At first glance, this might
seem a repudiation of API primacy, but actually most of
these companies dramatically expanded their programs. API
programs are now addressing both internal IT and integration,
as well as external-partner ecosystems that return even greater
ROI through building new products and driving innovation.
 TIBCO Success Guide | 2

Today, APIs are at the heart of just about every major IT

initiative, and their utility is only growing as market trends
continue to shift and consumers demand more personalized
access to their data through all of their connected devices.
The seven parts of this success guide explain how companies
can turn their APIs into a platform that effectively supports,
manages, and enables apps and channels, delights developers,
and grows business.

Understanding the Three Developer

Audiences
A successful API A successful API program is one that looks at all three
developer audiences — internal, strategic partner, and open
program is one ecosystem — and creates a coherent strategy that serves each
that looks at all group’s needs while meeting the goals of the business.

three developer The end consumers of your APIs can be expected to have at
least the requisite technical knowledge to make a call to your
audiences — API server and receive a text response. Though their total
internal, strategic technical knowledge will vary greatly and represent a spectrum
of different roles and experiences — from seasoned, dedicated
partner, and open engineers to amateur part-time dabblers — it’s easiest to
ecosystem — and think of them all as developers because they share several
requirements to get their jobs done:
creates a coherent
strategy that serves • An authentication token to access the system

each group’s needs • Searchable documentation describing all possible API

calls and parameters
while meeting • Knowledge about the data and rate limits placed on it by
the goals of the the API publishers
business. The details of these requirements will change based on the
audiences you’re targeting. Though you may create several
developer personas representing different customer segments, it
helps to start by defining the general levels of access they expect.

Partners
Developers

An authentication
token to access the
system

Searchable
documentation
describing all possible
Open API calls and Internal
parameters
Ecosystem Knowledge about the
Developers
Developers data and rate limits
placed on them by the
API publishers
 TIBCO Success Guide | 3

Internal Developers
It’s likely the developers within your own organization are
using third-party web service APIs and code libraries to
rapidly develop your applications. Many API programs were
started solely for the purpose of serving data to native mobile
applications, which often require an abstracted interface to a
server. But many development teams still connect directly to
databases and other code bases with little or no abstraction,
leading to rigid coupling and code dependencies that hamper
adoption of new technologies and the ability to change the
underlying system to pursue new opportunities.
It used to be a hard sell to convince development teams to
expose their functionality as reusable web-service APIs. Jeff
Bezos’ famous 2003 memo demanding IT teams interact only
through services or lose their jobs, was written specifically to
end this debate within Amazon. As a result, Amazon’s own
internal infrastructure management system, Amazon Web
Services (AWS) was eventually opened to the public and today
generates several billion dollars in revenue per year.
Architectural styles, such as microservices and function-as-a-
service, have normalized the use of APIs as the sole interface
to a server-based application, and support the kinds of API
programs we discuss here.
When internal When internal APIs are as well-designed, well-documented,
and well-managed as those offered to third-party developers,
APIs are as well- internal developers are often happier and more productive.
designed, well- By consuming the same APIs as your customers who are also
developers, internal developers intimately understand the
documented, and customer experience and tend to advocate for improvements
well-managed in design, performance, and utility, which ultimately benefits all
as those offered of your API consumers.
These APIs can also lead to more rapid development as
to third-party functionality is built once and re-used many times in a
developers, internal consistent, secure way. This allows product teams to take less
developers are risky bets on new features and functionality, leading to better
innovation and increasing customer value.
often happier and
more productive. Strategic Partnerships and Integrations
In terms of earned revenue, API programs focused on
strategic partnerships traditionally have the best ROI. These
partnerships are often formed when a specific customer need
or market opportunity is uncovered.
As an example, an email marketing company with small-
business customers joined with an online event management
platform provider to run customer events. The email company
provided its API to its event management partner to allow
pulling invitees from email lists, generating online tickets, and
 TIBCO Success Guide | 4

handling RSVPs. It also helped the event company develop

its own APIs that allowed customers to pull event information
directly into email templates to send RSVPs and event updates.
With cross-promotion of this new integration, both companies
saw significant uplift in usage and engagement, as well as
exposure to each other’s customer base and markets, resulting
in more customers for each partner.
Many web These kinds of success stories happen across all industries, and
the ability to integrate partner functionality and data into each
application and others’ systems — powered by APIs — has only made such
service providers partnerships stronger, improving functionality with minimal
development, maintaining focus on core competencies, and
continue to see real increasing customer stickiness by adding significant value.
value in an open
ecosystem. The Open Ecosystem Developers
Open ecosystem developers are the stereotypical “geeks in a
most successful
garage.” Many early API proponents expected to use their APIs
examples are to build applications that send droves of users to API providers’
companies that applications. Facebook and Twitter originally proved the value of
these programs by allowing developers to build semi-sanctioned
sell their data tools that helped enhance the social experience. Zynga built
through APIs, an entire gaming company simply through using Facebook’s
early APIs to develop games that appeared to be hosted
limit API access within Facebook’s main site. In return, Facebook saw increased
to customization engagement and usage as its customers logged in several times a
capability, or day to update and interact with their favorite games.
Customer Resource Management providers like Salesforce saw
maintain tight great adoption of their APIs by third-party developers. Third
control over access parties used the APIs to build out Salesforce.com’s application
to personal data. store, and customers used them to integrate Salesforce with
other systems. This type of customization leads to strong
customer loyalty and reduced churn as these systems amass
more data and become more valuable.
However, a number of the most successful and popular open APIs
either went private or significantly reduced their functionality. In
many cases, the reason was low ROI due to supporting thousands
of applications through an open API instead of focusing on fewer
strategic integrations and partnerships.
None of this is to say there is no utility in an open API
approach. Many web application and service providers
continue to see real value in an open ecosystem. The most
successful examples are companies that sell their data through
APIs, limit API access to customization capability, or maintain
tight control over access to personal data. With the right
approach, a third-party ecosystem can be a huge success.
 TIBCO Success Guide | 5

Lowering IT Costs & Monetizing Your APIs

A successful API program meets the goals of the business, and
all business goals can be boiled down to either generating
more revenue, reducing costs, or saving time.
The success of The success of your API program can be measured in a number
of ways: by judging usage through the number of API calls,
your API program tracking the number of active developers or users, monitoring
can be measured the speed of data that flows through the API endpoints, etc.
These metrics can help determine how well your marketing and
in a number of management efforts are working, but none are as important
ways: by judging to the business as how much money your API program is
usage through generating or saving your company.
Your API strategy will determine how you measure success, and
the number of it’s worth taking the time in the planning stages to think this
API calls, tracking through. It’s helpful to start with a simple model that breaks
the number of program measurement into five areas: improving operational
efficiency, leveraging and enabling strategic partnerships,
active developers driving revenue generating activities, adding value for upselling,
or users, and directly monetizing by charging for access.

monitoring the
Charge for Add Value for Drive Revenue Leverage Improve
speed of data that Access Upsells Generating Strategic Operational
Activities Partnerships Efficiency
flows through the
Per call or “Silver level Affiliate programs Share data Quickly respond to
API endpoints, etc. subscription and above”
Marketing
and functionality
with partners
market changes

Works well for data Ideal for SaaS automation Adapt to new
service companies businesses Revenue share with technologies
Ideal for partners
Assumes customers e-commerce Improve time
want custom Increase exposure to market
integration to partner customer
base

Examples Examples Examples Examples Examples

Sportradar VerticalResponse Amazon Uber Argos
Rovi Salesforce Shopify Pinterest Comcast
Netflix

Operational Efficiency
When open ecosystem APIs using RESTful web services first
hit the market, developers were thrilled by the amount of data,
functionality, and ease of access. These APIs did not lock them
into specific languages, frameworks, or environments, so they
could build applications with these APIs using the tools they
were most comfortable with.
An interesting side effect of this was that the developers who
produced those APIs often grew jealous of how easy their
developer customers had it. A third-party developer could
easily access JSON-formatted data through a simple RESTful
interface, while most internal development still required
proprietary or legacy standards and direct connection to
the code bases and systems they were accessing. This led to
dependencies that slowed development.
 TIBCO Success Guide | 6

In the early days, it took some convincing for IT departments

to begin abstracting their internal services and offering them
as APIs. Today, it’s considered a best practice with the highest
return on investment.

Adopting API- Adopting API-first development practices can significantly

reduce time to market for new digital products, often from
first development months to weeks. These improved efficiencies have results that
practices can go far beyond cost savings, though savings can be significant.
When it costs less to produce mature applications in less time,
significantly it’s easier to try things that might otherwise be considered
reduce time to risky. For example, if, someone on the executive team thinks
market for new a virtual reality client may generate revenue, a cost analysis
will demonstrate that the bulk of the budget would go into
digital products, developing the actual client application, with much of the
often from server side being provided by existing APIs.

months to weeks. This is exactly how companies like Netflix are able to support
so many clients with so many different needs. APIs are
These improved layered at varying places in the technology stack to allow
efficiencies have communication between services running on countless
machines. The back-end for front-end (BFF) pattern
results that go consolidates API calls between clients and downstream back-
far beyond cost end processes to provide more efficient communication over
limited channels without sacrificing service reusability. In the
savings, though
modern architecture stack, it’s practically APIs all the way
savings can be down, with tremendous benefits from reducing technical debt,
significant. reducing time-to-market for new products, and improving
developer onboarding.

Strategic Partnerships
Strategic partnerships are an ideal way to expand your reach
and capabilities with minimal cost. These partnerships often
take the form of co-marketing and co-selling, especially
in the analog business space. In the online business space,
strategic partners can share data, better integrate each
other’s functionality, and form a more cohesive experience by
consuming each other’s APIs.
Examples include embedding partner functionality into
your application to make it available to your customers,
leveraging a user’s data with a partner to pass it into your
system for easy integration, or even co-marketing using a
shared database of customers carefully segmented using the
additional information provided by your partners. Most of these
partnerships will be structured to split revenue, as a vendor-
client relationship, or simply by expanding market exposure for
each company.
 TIBCO Success Guide | 7

Affiliate programs are another form of partnership that may be

less strategic and focused, but potentially lucrative nonetheless.
In this model, you typically offer some percentage of each
completed sale the affiliate partner sends to your site. Setting
this up requires very specific tracking and reporting to ensure
both sides are sticking to the contract. But designing the API
to allow for the completion of the revenue-generating activity
can make the partnership more successful and result in higher
conversion rates.

Regardless of Regardless of the type of partnership, make sure you’re putting

the right tracking and reporting in place early and that both parties
the type of agree on the KPIs in addition to sharing any additional KPIs that
partnership, make are specific to each business. Having these in place ensures both
parties know what is expected of them and each can react quickly
sure you’re putting when the metrics don’t line up with expectations.
the right tracking
and reporting in Revenue Generating Activities
Web applications are typically optimized to drive customers
place early and
toward a specific revenue-generating activity such as
that both parties purchasing a product, booking a service, completing an action,
agree on the etc. The APIs associated with these applications are often
not types customers and third parties may be willing to pay
KPIs in addition money to access, but the functionality they provide to their
to sharing any applications can often be valuable if they would otherwise have
to build it themselves.
additional KPIs
In these situations, offering API access for free is a great option,
that are specific especially if the APIs are designed to drive revenue generating
to each business. activities. The email marketing company mentioned on page
2 under Understanding the Three Developer Audiences,
previously only recognized revenue when an email was sent
from its system. Its API program was designed to make it easy
to import new list members, create new mailing lists, add
content to an outgoing email newsletter, pull usage statistics
from sent newsletters, or send a newsletter. All of these
activities required that an email be sent. For customers seeking
more customization, designing the API around the activity that
generates revenue and offering it for free, made sense.
Measuring success in this case gets a bit more complicated,
especially if there’s no single API call that actually performs the
specific revenue-generating activity. Comparing the revenue
generated by accounts using the API against those that don’t
shows how well your API is performing.

Value Adds and Upsells

APIs designed with customer use cases in mind are quite
valuable; They add a layer of customization and usability with
a fairly low amount of effort. However, charging for these APIs
directly, in addition to charging for another account, may leave
many of your customers cold.
 TIBCO Success Guide | 8

If the goal of your API program is to add value and

customization for customers, consider either including API
access as part of your standard user subscription at no extra
charge, or creating different user tiers with API access included
at the higher tiers.
Opening your API to Opening your API to existing customers for free makes sense
when your API program is designed to increase customer
existing customers loyalty and stickiness, especially when your customers are
for free makes sense clamoring for programmatic access to their data. While it can
be difficult to track the revenue flowing through your API, you
when your API
can compare usage to the revenues generated by the accounts
program is designed using the API to get an idea of how much money it’s earning.
to increase Adding API access as a feature at higher user account levels
can be an attractive benefit for those seeking a bit more
customer loyalty functionality and customization. This approach generally
and stickiness, works best for web applications that already sell their services
especially when through various subscription tiers. Where your lowest tier may
offer basic access to your applications with some limitations,
your customers higher tiers may offer additional benefits, such as greater
are clamoring for access to existing features, exclusive access to non-basic
functions, and even access to your API.
programmatic
Salesforce is the classic early example of this kind of tiered
access to their data. account. When Salesforce first started offering API access
to customers, it was available as a feature for those who
purchased third tier access and above, whether customers
explicitly asked for it or not. This opened the API to the most
dedicated set of customers and forced those in the lower tiers
to consider what access to the API might be worth to them.
This allowed the teams supporting Salesforce’s APIs to focus
their attention on actual customer integrations rather than
dozens or hundreds of proof of concept applications built
by the open market. Salesforce also built and maintained its
AppExchange to allow third party developers to integrate with
Salesforce customers through a tightly managed process that
has proven beneficial to all players.
Salesforce still allows customization through its APIs at the
third tier (now called Lightning Enterprise), opening limited
access at lower tiers as well, allowing for greater but finer
grained control over API access based on customer type and
general use case.
Measuring the success of upselling API programs requires looking
at the customers and revenues in those tiers. To get an even clearer
picture, the revenue generated through accounts actively using the
API should be compared to the rest of the cohort.
 TIBCO Success Guide | 9

Direct Monetization
If you choose to directly sell API access, you’ll need to consider
how you will structure your program and accept payment.
Most often, organizations start by figuring out how much they
should charge for access. This is the most popular approach to
monetization, but it’s often the most challenging.
To understand why, again consider your target audience, the
goals of your business, and the value of your APIs to the
audience. If the purpose of your API program is to provide data
and functionality that you would otherwise sell or provide in
other formats to the open market, you likely have a good case
for direct monetization. However, if your APIs are designed to
provide value through third-party integrations, you may want
to consider other models.
Sportradar built its business by supplying reliable, real-time
sports statistics to media companies, sports applications, and
other digital sports channels. It provides clear pricing tiers
targeting different customer needs on its website. In most
cases, a customer can sign up immediately, provide payment
information, and begin accessing data immediately. Sportradar
is a model example of successful direct monetization.

Pricing Your APIs

Because APIs are not tangible products, pricing them can be
a challenge for companies that don’t sell software. In general,
products are priced to make a profit — you cover the cost of
the parts, labor, and distribution, set a profit margin, and you
have your price.
One simplistic but The cost of developing, hosting, and supporting your APIs may
already be built into your IT budget, especially if you follow the
effective way to best practice of having your internal teams use the same set of
figure out the cost APIs your customers use.
of hosting your API One simplistic but effective way to figure out the cost of
hosting your API is to look at the run costs of the system
is to look at the run supporting it (the bandwidth charges, server hosting fees,
costs of the system equipment costs, administrative labor costs, etc.). Or, if your
entire system is API-led, look at your total IT budget and divide
supporting it (the
by the number of calls or operations your system currently
bandwidth charges, supports. You can use this cost-per-call number to budget for
server hosting fees, your expected growth needs for supporting a wider audience
and as the basis for your pricing decisions. Remember to
equipment costs, refresh your cost-per-call estimate frequently to compensate
administrative labor for any changes introduced by re-architecting your system or
moving to different infrastructure providers.
costs, etc.).
 TIBCO Success Guide | 10

When selling to The next step is to understand what price your target market
will respond to. Review what similar API programs or other
developers, the two services charge and see how your cost-per-call plus profit
greatest values they margin expectations stack up. If your prices are higher than
average, promote the unique value your APIs offer. When
look for are ease selling to developers, the two greatest values they look for are
of use and breadth ease of use and breadth of functionality. If you can make their
of functionality. jobs easier and reduce their development time for a reasonable
cost, you’ll win their business every time.
If you can make But keep in mind that your end users are rarely the ones who
their jobs easier make the purchasing decision. Developers will make their
and reduce their recommendations to their management teams, who will find
money in the budget to make the necessary purchases. Arm
development time both your sales team and your developer customers with the
for a reasonable right messaging, knowledge, and value proposition to help
them convince their superiors that you’re worth the purchase.
cost, you’ll win their
business every time. Per-call Pricing vs. Subscription Tiers
How you charge for access has a lot of influence over your
actual pricing. In the direct monetization model, there are two
ways to charge for access: per-call or through recurring billed
subscription tiers.

Per-call Pricing
The benefit of per call pricing is that you can easily account for
revenue. If each call costs your team $0.005 and you charge
$0.01 per call, you can see where profit starts, which makes it
easy to forecast revenue based on traffic patterns.
But this ease can come at a significant cost for your customers.
It’s difficult to estimate how many calls any application will
have to make, which complicates cost forecasting. APIs that
require more calls for fairly simple functionality (aka “chatty”
APIs) cost more than those that are efficiently designed. The
cost-per-call figure is also not usually consistent across all
API calls — some require more data transfer or CPU power
than others, which leads to uneven expectations in revenue
reporting. Complicating all this are changes to API design best
practices. The GraphQL API format, which allows for greater
client control over the amount of data requested and returned
in a single call, breaks the per-call pricing model completely.
Per-data (per kilobyte, per megabyte) pricing models are
similarly complicated for many of the same reasons.

Tiered Subscription Pricing

Subscription tiers offer a better way to charge directly for data
by allowing customers to better predict their costs based on
fixed pricing and average cost per call across a larger pool.
This approach minimizes revenue fluctuations across different
usage profiles for different endpoints.
 TIBCO Success Guide | 11

If you cannot help As you research your target market and its pricing sensitivity,
segment it into three to five distinguishable groups. These
developers get groups form the basis of your pricing tiers.
to market faster To help decide on exact pricing, ask your team:
or can’t provide • How many calls might we expect applications built by
unique data and customers in each tier to make per month?

functionality that • How valuable are our APIs to the success of each tier’s
applications?
would otherwise
• How much revenue do we expect their applications to make
require a lot of work for them?
on their part, you • What are the estimated costs associated with these tiers
using our cost per call number?
will not win them
• What is our estimated cost at the top of the range of each
as customers. tier vs. the bottom?
• What is our estimated cost across the entire spectrum of
each tier?

The answers to these questions will help you make better informed
pricing decisions to arrive at reasonable and affordable pricing for
customers while generating a steady profit for the business.

Creating an Optimal Developer Experience

Developer audiences are often thought of as a vocal and finicky
bunch, and with good reason. The pressures put on modern
developers are tremendous. The business expects innovative
products that can serve thousands of users with little to no
downtime, and with no security flaws that expose customers or
the business to bad players, and they want it yesterday.
While the best developers are driven by factors including
building social capital, demonstrating expertise, and sharing
knowledge with others, there are two things they value above all
the rest: their time and effort.
Every aspect of your API and overall developer experience
should be optimized for those two values. If you cannot help
developers get to market faster or can’t provide unique data and
functionality that would otherwise require a lot of work on their
part, you will not win them as customers.
Those targeting an internal program should take heed that the
same holds true for fellow employees. The best programmers will
hack their way around management decisions they don’t think
are the best way forward. Simply providing APIs will not suffice;
you must consider the entire experience, from onboarding to
support to API design.
 TIBCO Success Guide | 12

Developer Portals
If you are targeting a developer audience, provide them with
a portal for accessing all of the information they need to sign
up and start using your APIs. A dedicated developer portal
hosted on your company website or separate domain (e.g. http://
developer.example.com) is the best way to help developers
navigate through your documentation, register for API keys, and
get the support they need as they build their applications.

This is an example of what a developer portal could look like. This specific
one is for airline travel.

For programs targeting an open developer ecosystem, the portal

is a key part of developer marketing and outreach. The main
page should clearly spell out the value of the API for them, how
it saves them time and reduces their development effort, as well
as the steps required to get started.
Portals targeting strategic partners and internal teams aren’t
much different than for an open ecosystem. All include a bit
of marketing to reinforce the value of your APIs to help them
understand why they’re using these services. Elements of a
successful API portal:

• Thorough, searchable documentation

• Clear path to registration
• Clear path to developer support
 TIBCO Success Guide | 13

Thorough, Searchable Documentation

If your portal does nothing else, it must provide the best
documentation available for your services. Good documentation
significantly reduces developer time and effort by providing clear
and well-organized information appropriate for every expected
developer maturity level. For example, more mature developers
may not appreciate a page dedicated to how OAuth 3.0 is
implemented, but more novice developers may find it helpful as
they try to access your APIs for the first time. Offering this type
of information in a separate static web page linked in the table of
contents will allow those who want that information to find it.
It’s best to break documentation into two groups, static
and interactive.

This Open API dashboard shows developers what data they can integrate
into their own applications.

Static Documentation
The vast majority of documentation you provide will likely be
static manuals, web pages, and tutorials intended to be read and
followed, without any “try it now” type features.
For static documentation, your best bet is to stick with HTML
pages that are divided into easy to scan categories. The best
static documentation provides narrative instructions rather than
lists of available functions, endpoints, and parameters. Cover the
basics on how to get started with your API — how to register for
a key, how to properly use and store that key, and how to make
a simple call. Then start focusing on the most common expected
use cases. For example, an e-commerce application would have
pages documenting how to get items from a store, how to put
an item into a customer’s shopping cart, and how to check out
and accept payment.
 TIBCO Success Guide | 14

Be liberal with Be liberal with your use of example code; it’s more effective to
see the calls in action to best understand the intent of the APIs.
your use of Provide sample code either as pure pseudocode, or better, as
example code; it’s actual code in the languages most popular with your developer
audiences. Many developers will try to save time by cutting and
more effective pasting your sample code directly into their projects, so be sure
to see the calls it is syntactically valid and compilable.
in action to best Avoid use of PDFs or any format that requires special programs
to browse and search. The web browser is usually the best tool
understand the for browsing and searching documentation. PDFs can be bloated,
intent of the APIs. difficult to search, and require a PDF reader to use adequately.
Provide sample Stick to straight CSS and HTML for your documentation, and
your developers will thank you.
code either as
pure pseudocode, Interactive Documentation
or better, as Thanks to the Open API Spec (OAS, aka Swagger), developers
consuming web services are often blessed with the ability to
actual code in try calls directly from their browser without writing a line of
the languages code. The OAS allows API providers to document every aspect
of their API — endpoints, request and response parameters,
most popular with URLs, common data objects, and more. Using a variety of tools,
your developer the spec can easily be converted into a set of web pages that
audiences. allows developers to make calls directly from their browser and
immediately see the results.
These pages are key for early stage development where a
programmer is merely figuring out what is possible with the API.
They act not only as documentation — a better form of detailed API
description than the traditional service dictionary — but also as a
prototyping tool. Some developers may even cut and paste the calls
directly from these pages to form the basis of their application.
As a web service provider, you should absolutely provide
interactive documentation for all of your developer audiences.
The OAS and many supporting applications are open source
and free to use and implement. There are several competitors —
Apiary Blueprint, RAML, and IO Docs to name a few — but the
acceptance of the OAS across the industry makes it the clear
winner and the one you should adopt for your program.
The OAS can be used for far more than just documentation.
API tooling providers, such as TIBCO with its TIBCO Cloud API
Management solution, often use OAS to configure how APIs are
served and managed. OAS is also starting to find its way as a
tool to help reduce developer time by dynamically creating SDKs
and support code to more easily access web services.
 TIBCO Success Guide | 15

Clear Path to Registration

The simplest registration is one that is self-service, requires
no additional validation, and provides an API key immediately.
However, even a process this simple should be thoroughly
explained, even if only by using a simple diagram.

Step 1 Step 2 Step 3

Register for an account Integrate functionality Deploy application

Create an account Review our API Make requests to our

and we’ll assign a resource API endpoints with
client ID and API key documentation and your authenticated
for each of your explore our developer credentials.
applications. console.

More complex APIs, especially those targeted to strategic

partners and internal developers, will likely require some
kind of human-led validation process before registration can
be completed. Be clear about all requirements and timing
expectations at all points of the registration process by
implementing the following:

• Explain how to sign up on the homepage of your

developer portal
• Describe your expectations and timelines on the
registration page, (for example, “Access is only available for
our corporate partners and staff. It may take up to three
business days before your account is created.”)
• Make sure you reiterate on the confirmation page and any
subsequent confirmation communications the time it should
take before they are approved.

Clear Path to Support

When a developer gets stuck, they will typically turn first to
your documentation. If they don’t find the answers there, they
will look for whatever support you provide. Failing that, they will
likely turn to sites like Stack Overflow to see if anyone else has
run into a similar issue and found a solution.
Good documentation that is regularly updated to address the most
common issues developers report will address a vast majority of
support requests before they’re even filed. Still, developers will
find interesting edge cases and unique uses that will require the
intervention of someone with more expert knowledge.
 TIBCO Success Guide | 16

The design of your The first line of support after your documentation should be
an email address or phone number monitored by someone on
API — how calls your staff who can address developer-specific support issues
are made, how and even walk through the code themselves. Be clear what your
support level agreements are and support them faithfully.
data is formatted,
Even with a support line, many developers will turn to the
how resources are communities they trust to find answers. You may provide
linked together — your own set of forums for developers, but if they are not well
monitored and well populated, most will skip them completely
has tremendous and go to sites like Stack Overflow. Stack Overflow gets a lot of
influence on love in the developer community because of how searchable it
whether developers is and how willing its members are to provide reliable help. In
most cases, the issue someone is searching for has already been
will use it. addressed, so it’s a matter of reading and applying the response.
Your support staff should be monitoring Stack Overflow and
any other similar sites that you know your audience uses. They
should actively and publicly answer any questions specific to
your APIs and applications while also trying to follow up with
more personal support if the situation warrants.

Designing and Managing APIs

A well-designed, well-managed API is a delight for developers
to use and product managers to support. The design of your
API — how calls are made, how data is formatted, how resources
are linked together — has tremendous influence on whether
developers will use it. Its design should be given the same level
of care and concern as the design of your company’s website.
Good API management ensures the right people are accessing
the right data at the right time. It helps your product and
development teams monitor usage and highlight opportunities
for improvement, and allows the API program to scale seamlessly
as more developers come on board.

API Design
Designing your API is a topic better covered elsewhere, but there
are many basic considerations you should keep in mind as you
approach the design of your services.
REST is a popular design strategy largely because of its close
adherence to the HTTP protocol, which makes it fairly easy to
implement with many of the same infrastructure requirements as a
website. The best practices introduced by REST — specifically, the
use of decoupled, independent resources linked via URLs as the
central organizing principle — have influenced the designs of much
of the modern architectural stack, especially microservices and
functions as a service. Though REST can deliver its data in just about
any format supported by web standards, JSON has emerged as
the de facto standard for most REST implementations because it is
lightweight and relatively easy to analyze.
 TIBCO Success Guide | 17

SOAP was originally designed for server-to-server

communication over networks that can handle high-bandwidth
loads. The XML formatting of SOAP messages allowed for tight
validation and control of formatting, allowing much of the error
checking at both client and server to be mostly boilerplate, and
development to be fairly rapid. SOAP fell out of favor as a public
API format largely because of its overhead requirements and the
complexity in parsing XML. However, it still finds dedicated usage
in environments where transactional integrity and adherence to
well-established standards are highly valued, such as in financial
and governmental institutions.
New formats seem to be emerging regularly, building on the
strengths of their forebears while addressing weaknesses in the
older ways. gRPC, for instance, is a binary API format that offers
rapid communication and tight validation in a package more
efficient than SOAP. Its binary formatting and functional nature
requires a bit more work both on the client and server sides to
implement, but the gains can be worth it if the use case fits.
GraphQL, a format created by Facebook to more efficiently
query large, distributed datasets, is gaining a lot of traction in
the REST community as it addresses many of REST’s limitations
in retrieving data across many resources. While GraphQL can
also update that data in a similar call, its loose data structure
may lead to confusion in some cases. GraphQL is often best
when used in conjunction with REST.

The protocols you The protocols you adopt and data formats you choose should
always be based on your specific use cases and the needs of
adopt and data your developer audiences. Ignore the debates that definitively
formats you choose declare one better than the other; Instead, focus on building API
endpoints that:
should always be
based on your • Represent independent business objects in your system
• Interact with other objects within the system in a
specific use cases transparent way (for example, through their own API
and the needs of endpoints)
your developer • Are decoupled from any specific use cases

audiences. • Are reusable by multiple applications

API Management
The first public APIs were simply put behind an authentication
layer, served through a load balancer, and loosed upon the world.
Early API teams quickly ran into the limitations of relying on
server logs for metrics, adding more load balancers to scale the
system for more developers, and ensuring their authentication
was secure and properly controlled access to the right endpoints.
 TIBCO Success Guide | 18

API management as a product emerged as an ideal solution to

address the challenges of scaling, securing, and supporting an
API program. TIBCO Cloud API management software was one
of the first of these products to go to market and has matured
into a consistently recognized market leader addressing the
specific needs of API programs, where others were often built on
legacy, unwieldy SOA systems.
Well-managed APIs can easily scale at the server application
level and the caching layer to offer optimal performance
regardless of traffic load. Retail customers are often most
concerned about performance during high-peak traffic times
around the holidays. By using an API management system and
planning for usage spikes on their backend, the most successful
e-commerce systems are able to handle the flood of holiday
traffic with practically no additional IT effort.
Data security is often cited as one of the main reasons an
organization is hesitant to open their API to outside users. For
internal developers to build their applications, separate security
access is often required on several systems such as databases
and ERPs. Managing these accounts can be costly and difficult.
Abstracting this access behind APIs and using the built-in
authentication and authorization features of an API management
platform, the API team can easily control who is accessing which
data in a single administrative interface. The same API endpoints
designed for internal developers can be securely filtered to
remove internal-only data and served to external developers with
very little effort.
The best API management systems also provide tools for
monitoring the API and supporting developers, including built-in
developer portals and custom reporting on usage based on user
type, API package, region, and more. Support staff can review
these metrics to understand how a developer is trying to use
the API and troubleshoot any issues that result. The product
management team should review usage statistics regularly to
understand which endpoints are being used most, how well the
system is performing, and to seek improvements that can be
made to better delight their developer audiences.

Going to Market with Your APIs

Whether targeting open developers, strategic partners, or even
your own engineers, putting your best foot forward with the
right messaging and a solid roll out strategy can help get you to
success faster.
 TIBCO Success Guide | 19

With your first set of APIs designed and managed and your portal in
place, your go-to-market plan should cover the following:

• Developer Outreach - Reach out to your developer

audiences with messaging that addresses their needs.
• Developer Onboarding - Create an experience that gets
developers up and running quickly.
• Developer Feedback - Listen to and observe members
of your audience to identify opportunities to improve the
overall developer experience.

Developer Developer Developer

Outreach Onboarding Feedback

Developer Outreach
Your portal stands How you reach developers will largely depend on the types of
developer audiences you are targeting. However, there is quite
as the primary a bit of tactical crossover you can leverage to reach all types of
point of entry developers, saving you time, money, and effort without reducing
the effectiveness of your outreach.
with information
Your portal stands as the primary point of entry with information
for all developer for all developer audiences. A majority of your content and
audiences. A marketing efforts should be spent pointing developers to the
portal and guiding them down the paths that will lead them
majority of to success. As you structure your documentation and tutorials,
your content keep these audiences and their respective paths in mind.
and marketing Consider creating second level landing pages designed to serve
the needs of each developer audience, and use these links in
efforts should be your marketing and outreach materials rather than just your
spent pointing developer homepage.

developers to the It’s a myth that developers don’t like being marketed to. The
truth is that no one really likes being sold to, but the developer
portal and guiding audience tends to be more vocal and critical than the average
them down the customer. The same marketing campaigns that work well for
your average customer should also work for developers —
paths that will lead email newsletter campaigns, paid ad placements, conference
them to success. sponsorships, etc. The key difference is that all of your
messaging should very clearly demonstrate the value of your
services for developers. The two values that matter most are
saving time and reducing effort. Your marketing messaging
should not just pay lip service to these values; it should
demonstrate as clearly as possible how your services provide this
value with a call to action to try it for themselves.
 TIBCO Success Guide | 20

As you define your developer audiences, pay attention to the

events they attend, the sites they visit for information, and how
they prefer to communicate with vendors. This information
will guide your ad and event spend and help you prioritize the
materials you should produce.
Developer meetups are one of the better places to meet your
potential customers face-to-face and give them a more in-depth
idea of how your services can help them. Meetup.com is the
most popular place to find these events and perhaps organize
one for your own customers. Ask developers about any other
meetups they attend and consider adding them to your roster.
One of the cooler types of events targeting developers are
hackathons. Just as the name implies, a hackathon is a marathon
coding session usually held over a weekend where teams
compete by building applications or technical solutions either
using the technology of sponsoring organizations or addressing
specific real-world problems. The hackathon space has matured
dramatically over the past decade from large free-for-all
marketing events to more focused events held throughout the
year. Many are hosted in conjunction with big tech events, like
API World or TechCrunch Disrupt. Others are held at universities
and colleges to identify new talent and encourage early-career
adoption of certain tools and services.
As you approach a hackathon, whether as a sponsor or host of
your own, make sure you have a clear understanding of your
goals. Many organizations sponsor these events with the hope
of using cheap talent to produce new product ideas. They’re
rarely successful, especially given that most hackathon entries
are designed to work by the time the demo comes, not to be
put into production. A better strategy is to use these events to
identify potential talent for hiring, activate customer advocates,
get real-time, real-world feedback on your products, and see
real developers interact with the experience you’ve designed for
them. A hackathon is an opportunity to tell people about your
developer-focused products, but it’s an even greater opportunity
to listen to the very audiences you’re trying to grow.
All of this may seem geared toward targeting developers outside
your organization, but internal meetups, lunch and learns, and
even internal hackathons are great ways to energize your
development teams and encourage them to adopt and build
using your organization’s APIs.
 TIBCO Success Guide | 21

Developer Onboarding
Onboarding new developers starts with your developer portal.
Everything they should need to begin work using your tools and
services should be clearly documented there. The registration
flow may be the first step to onboarding, but it’s absolutely not
the last.
Pay attention to how many developers start and finish registration
versus those who only start and never complete the final steps. If
you’re seeing a large number of dropouts in the process, or even a
large number of successful registrations that never actually use your
APIs, this indicates a problem with your onboarding flow. Dropouts
often indicate that your registration process is too complicated
or that you’re asking for information they don’t want to provide.
At signup, only ask for the minimum information necessary to
provision a new account. You may fill in any additional demographic
information in subsequent interactions.
If you’re seeing a large number of signups but few of them
actually use your services, this may indicate that your
documentation is not closing the gap between knowledge and
execution. Review your documentation and tutorial content and
look for areas that may be causing confusion. Consider reaching
out to some of those who dropped out and asking them for
recommendations for improvement.

Developer time is After a developer has signed up, you should send them an email
confirming their signup. If your process requires additional
precious, so try to approval steps before a key is provisioned, be clear about what
keep the sign-up that process involves and how long it should take. In these
situations, the developer is often standing by and waiting for the
process as short as approval before they can continue with the work they’re doing.
possible and make Developer time is precious, so try to keep the process as short as
sure you stick to possible and make sure you stick to the advertised timelines.
If your APIs require approval for use, consider providing a
the advertised sandbox environment where the APIs match exactly with your
timelines. production endpoints, but provide fake data until your team
approves the developer account. This allows your customers to
begin programming against your API without delay. When you
have provisioned the production keys, the developer merely
needs to swap these out in their code to start using it with
production data.
 TIBCO Success Guide | 22

A sandbox is also good for allowing developers to get a better

handle on your API in their code without impacting live accounts.
Most developers follow the try-break-learn-fix cycle of learning.
They try something out given the code and documentation
provided, somehow break their code in the process, dig through
their code and the documentation to learn exactly what went
wrong and why, then fix their code, and repeat the cycle until
it works. This style of experiential learning is tremendously
valuable, and you should do everything you can to support it in
your developer experience.

Software Try
development
kits (SDKs) are
another approach
that can help
get developers
Fix Break
up and running
quickly. SDKs are
essentially pre-
built libraries
for the most
common languages Learn
your developer
audiences use Some developers benefit from receiving regular updates from API
that allow them providers shortly after registration. These communications keep your
services top of mind as your customer explores other technologies.
to access your
Make sure these communications are more than just marketing fluff.
services directly Provide value for the developer at each point of communication.
from native code. One suggestion is to create drip-style tutorial campaigns, regular
communications via email or other channels that walk through
interesting use cases your services can support. If you can structure
these campaigns to address the specific needs of your target
audiences, you should see good results.
Software development kits (SDKs) are another approach that
can help get developers up and running quickly. SDKs are
essentially pre-built libraries for the most common languages
your developer audiences use that allow them to access your
services directly from native code. This can shortcut the process
for many developers who would otherwise need to spend time
writing the supporting code to consume your APIs.
 TIBCO Success Guide | 23

A word of caution on SDKs. Because they often require hard

coding of certain calls, they need to be maintained, versioned,
and updated right along side your services. You should strive to
track who is using your SDKs and be sure to launch new ones
at the same time you make any major updates to your APIs.
SDKs effectively become separate products that must also be
managed, which can add burden to smaller teams. There are
automated SDK generators on the market capable of taking your
OAS and turning it into code. These are great time savers for
both the API product team and API consumers, but the resulting
code is not always the most efficient.

Developer Feedback
Your APIs should be treated as living products that will change
and improve to meet the demands of your customers and new
opportunities in the market. A majority of these improvements,
not only to the APIs, but to the entire developer experience,
should be driven by feedback from your developer audiences.
Create a feedback mechanism early on between your product,
engineering, developer support, and outreach teams to make
sure you’re tracking timely feedback and getting the higher
priority suggestions into your deployment cycles. It can be as
complex as an off-the-shelf issue tracker like JIRA, or as simple
as sending suggestions to an email address and compiling them
manually into a spreadsheet. The key is to track the number
and type of requests, group them together by category, related
codebase, and priority, and make sure you’re including that
feedback in your product development process.
As mentioned, hackathons and meetups are great ways to
expose your APIs to your target audiences and get real-time,
real-world feedback. Product managers should attend as many
of these events as their schedule allows to get a first hand
account of how their products are being received. Don’t be
afraid to hop on to a hackathon team and pitch in. Getting your
hands dirty is often the best way to earn trust and gain valuable
information that will only make your products better.
Your API management platform should come with a full set of
reporting tools built in. Product managers should review these
reports regularly. The number of calls and active developers are
often cited as success metrics for API programs. While they do
indicate how much usage your services are getting, it is nothing
when compared to KPIs that measure the revenue your APIs
are driving.
 TIBCO Success Guide | 24

However, these and other metrics can be used to help you focus
your efforts on improving the developer experience. Some
metrics to watch include:

• Number of calls per endpoint. Endpoints with significantly

low usage may not be needed or may contain data that is
better integrated with other calls. Those with higher usage
should be as performant as possible.
• Amount of data per call. High-data calls that are not
sending lists of objects are often an indication of
overloaded endpoints. Consider breaking the data into
separate endpoints and linking them via their URLs.
• Response errors. HTTP error codes, especially those in
the 5xx range, can indicate performance problems and
infrastructure issues. Response codes in the 4xx range (404
Not Found) can indicate that your documentation is out of
date or that some customers are expecting access to data
for which they don’t have authorization (401 Unauthorized
and 403 Forbidden) especially.
• Number of calls per user. Looking at who is accessing your
API the most can indicate users who are seeing success
using your services, potentially uncovering new application
ideas and potential partnerships. One rather successful
open API program actually uncovered a use case this
way that led to a $14 million partnership. Excessive usage
may also indicate bad actors or poor code that could be
better optimized to reduce the load on your servers while
providing a better experience for your customers.

Evangelizing and Advocating Your

API Program
It should be clear by now that a successful API program requires
a healthy investment in technology and staff to support it. An
engineering team taking an API-first approach to development
will already be generating APIs that will be exposed to your
targeted developer audiences. You may need to shore up your
support staff with more technical people to help address the
unique needs of developers when they contact you for help.
Your marketing team should be able to handle a majority of the
campaigns and event planning required to reach your audiences.
In most cases, you can easily integrate your API products with
the rest of your product strategy without requiring a special
team to handle it all.
 TIBCO Success Guide | 25

Developer However, most API programs — including those targeted to

internal engineers — benefit from the hire of one or more
advocacy is developer advocates or evangelists. This role can be difficult
focused on to fill because it requires someone with equal parts marketer,
showperson, and developer.
representing
Developer evangelism is largely focused on marketing activities.
the developer The evangelist attends and speaks at events; supports, sponsors,
audience within and participates in hackathons; and is the face of the company
to the developer community. They often jump in to support
an organization, complicated developer questions and problems in lieu of a
advocating on dedicated support team. If you’ve ever attended a developer
their behalf for event and seen a group of people wearing the same color
jacket or shirt advertising the same company, you’ve likely seen
an improved developer evangelists in action.
developer Developer advocacy is focused on representing the developer
experience and audience within an organization, advocating on their behalf for
an improved developer experience and additional features, and
additional features, representing their unique needs in product and management
and representing discussions. If your API is internal-only, your developer advocate may
be a lead on your API product or development team. They are the
their unique needs person or group of people to which everyone on the engineering
in product and team can turn to get answers to thorny technical problems.
management Rather than hiring for separate roles, it’s a best practice to
have one team dedicated to both evangelism and advocacy.
discussions. Developer evangelists should be expected to not only market
and support their API programs, but to take a seat at any table
where the developer audience needs an advocate. By living
in both worlds — advocacy and evangelism — they can better
address developer needs, better speak to your organization’s
developer-friendliness, and maximize their efforts to help grow
your developer audiences and bring your program to success.

Global Headquarters TIBCO Software Inc. unlocks the potential of real-time data for making faster, smarter decisions. Our Connected
3307 Hillview Avenue Intelligence platform seamlessly connects any application or data source; intelligently unifies data for greater
Palo Alto, CA 94304 access, trust, and control; and confidently predicts outcomes in real time and at scale. Learn how solutions to our
+1 650-846-1000 TEL customers’ most critical business challenges are made possible by TIBCO at www.tibco.com.
+1 800-420-8450 ©2018–2020, 2021. TIBCO Software Inc. All rights reserved. TIBCO, the TIBCO logo, and TIBCO Cloud are trademarks or registered trademarks of TIBCO Software
Inc. or its subsidiaries in the United States and/or other countries. All other product and company names and marks in this document are the property of their
+1 650-846-1005 FAX respective owners and mentioned for identification purposes only.
www.tibco.com 19Oct2021