How to Spot a Great API

HOW TO SPOT A GREAT API
The 7 Traits of a Strong Data Integration API
Whitepaper

Table of Contents
Preface.............................................................................................................................................. 2
Attributes of a World-Class Data Integration AP....................................................................... 2
1 – OPEN STANDARDS VERSUS PROPRIETARY ARCHITECTURE.......................................... 2
2 – CHANGE DATA CAPTURE.......................................................................................................... 3
3 – PERFORMANCE AND EFFICIENCY ......................................................................................... 3
4 – Meta Data Driven..........................................................................................................................4
5 – CONSISTENCY AND OBVIOUSNESS.......................................................................................4
6 – SECURITY.......................................................................................................................................4
7 – USER EXPERIENCE...................................................................................................................... 5
Closing.............................................................................................................................................. 5
About Scribe Online....................................................................................................................... 6
Whitepaper:
HOW TO SPOT A GREAT API
The 7 Traits of a Strong Data Integration API

Follow us on: Connect with us: 2
Preface
A desire for business agility has fueled the adoption of cloud computing and applications available as software services (a.k.a.,
software as a service, or SaaS, applications). In certain application areas, such as CRM and ERP, adoption of SaaS versions of
these applications has been measured, but steady, and in other application areas, such as marketing automation and human
capital management, the adoption of SaaS versions has been rapid and now represents the majority of the applications used
in those sectors today. Across the board, however, it is apparent that the efficiency, agility, and long-term supportability of
SaaS applications has been proven and is fueling an increase in the number of applications being deployed at enterprises. In
the evolution of the SaaS application market, the evaluation criteria for SaaS applications has moved beyond simply proving
that the application can deliver the necessary core functionality, but rather how well can that application fit in with all my other
SaaS and on premise products. For SaaS providers, this means it’s time to grow up. If your application can’t share data with
a broader set of applications and processes, you will be replaced by an application that does. Integration is now table stakes
for SaaS applications.
The challenge for SaaS providers is that every customer’s integration needs are unique. Not only does the combination of
applications and data stores that need to be integrated vary from company to company, the nature of the data and how it
needs to be shared across functions is also exclusive to each business. For SaaS providers, it’s about making their application
“integrate-able” and flexible enough that it can solve every customer’s integration needs.
At the core of any SaaS provider’s integration strategy has to be their application programming interface, or API, as well as
the API’s of those applications around them with which they need to integrate. Ensuring that these APIs are designed for
integration – meaning they support the many scenarios of data interchange that customers will need and are easy to work
with – is essential to having a successful API strategy. SaaS providers with the best APIs for integration understand that the
API is just as important as the user interface, in other words, part of your product offering, and needs to be treated with the
same level of care and investment.
Attributes of a World-Class
Data Integration AP
Over the course of nearly two decades, Scribe Software
has worked with hundreds of software providers and the
companies they serve. Through that experience, we’ve come
to recognize the attributes of the very best APIs. Generally,
APIs are developed to 1) support data level integration
between your application and other applications or data
sources or 2) enable developers to develop new application
functionality on top of or along side your application. Our
focus, is on the former.
We define data integration as a process that reacts to changes
in a set of separate data stores based on rules. We focus
on the attributes that allow for the following key capabilities:
the data sharing will be ongoing, will include both insertion,
but also extraction of data, and supports evaluation and
adherence to governance. The seven attributes listed below
will determine if an API provides the necessary capabilities to
allow the application to share data. These attributes can be
usedin twoways:1.You can focus on buildingtheseattributes
into your application’s API if you want to rise above your
competition and deliver software that will earn customers’
long-term loyalty because of its ability to share, and 2. You
can use these attributes to evaluate an application you want
to integrate with to see how easy it will be to integrate that
application with your existing infrastructure.
1 – OPEN STANDARDS VERSUS
PROPRIETARY ARCHITECTURE
One of the first choices a SaaS provider will make is whether to
build the API using open standards—such as representational
state transfer (aka REST) or simple object access protocol
(aka SOAP)—or create a proprietary architecture. Both
approaches can provide a great API but most should opt for
open standards. While REST and SOAP can layer on additional
overhead to an API design, this is generally overshadowed
by the fact that a large percentage of developers who will
utilize the API are familiar with these standard interfaces.
Open standards maximize the integration capability of the

software and provide greater freedom to customers. And if a
SaaS provider is deciding on a standard today, REST (along with
JSON-based data exchange) is currently the preferred choice.
2 – CHANGE DATA CAPTURE
Change is the driving force of integration. Each integration
begins with the “big change”, when a data store is added to the
integration process. When designing an API, understanding
the various sources of data, the type of data, volumes and
timing constraints must all be considered. Can an initial data
load be completed via the API?
After the initial synchronization, ongoing change becomes the
force. Therefore a critical function within the SaaS application
is the ability to identify the small changes to data. So that only
data that has changed since the data source was last integrated
can be identified and processed. At a minimum, for all objects a
SaaS provider should allow access to a date/time stamp, along
with an “updated by” field that identifies the user(s) who made
modifications. Integration processes can then periodically poll
for all records that have been updated since the last time the
record was modified. Designating the user enables the SaaS
provider to ignore changes that another application made,
which avoids creating an endless loop of integration updates.
While the date/time stamp method is straightforward, it does
have two major limitations. First, it fails to identify when
records are deleted, since those records will no longer show up
in any query. And second, polling approaches tax your server
(see sections below on Performance and Governance) and
can be highly inefficient. One approach to solving this issue
is implementing a change publishing capability where users
can identify changes they want to capture and then the API
publishes those changes to a secure Web services endpoint as
they happen.
3 – PERFORMANCE AND
EFFICIENCY
When it comes to APIs (especially those exposed in a multi-
tenant environment as a shared resource), customers typically
have high expectations. They want a magic mix of speed,
functionality and flexibility. They want the API to provide high
throughput (pushing large amounts of data through the API in
short time windows) and low latency (lightning fast response
time for individual records or requests) while enjoying precise
control over the integration business rules. The best way to
evaluate an API’s performance and efficiency is to document
the real-world use cases that are important to you and
associated performance requirements. Those use cases then
serve as the benchmark for the performance standards the
API will need to achieve.
Traditionallysoftwaremakershavebeenpressuredtospeedup
the rate of data being created or updated in their applications,
as this has been the big bottleneck in application-to-application
integration scenarios. With the buzz around Big Data, the
need to serve up queries of large data sets for analytics and
reporting is becoming more and more imperative. A great API
will meet performance benchmarks when moving data in both
directions.
An API that reduces the number of calls between itself and the
API of another application to perform a function is another
great characteristic that will address performance and
efficiency. Some key ways this is accomplish are:
• Bulk support - This refers to enabling users to request
or pass bulk arrays of data through the API. The SaaS
provider can then process these requests back on its
servers in highly scalable and performant manner.
Implementing bulk import or export capabilities can yield
record processing speeds that can be 10 to 100 times
faster than from a transactional API. In many scenarios,
where record-by-record validation isn’t required, this is a
highly valuable feature.
• Combination operations - Facilitating combination
operations such as “upserts” (updating and inserting
all in one API call) enables the API to perform some of
the advanced logic required for certain activities, which
reduces the number of API calls. However, there is a
balance to maintain here; the more customer control that
are allowed related to this interaction, the more API calls
may be necessary—and the time and expense required
for these operations will rise accordingly. For example, a
process may require information from a SaaS application
prior to determining how to process a record. This run-
time level conditional processing might not be achievable
utilizing an upsert.
• Message publishing - See the “Change data capture”
section above.
• Multi-threading - This enables a single API user to open
multiple threads of interaction within the same user
session, thus enabling integration processes to operate
at much higher speeds. Care should be taken to ensure
that the API is “thread-safe” so that separate processes
do not trip over one another.

• Support for both batch and real-time processes – Users
of the SaaS applications will have scenarios where they
need to integrate large batches of data on a schedule
while other use cases will require support for real-
time processes. In fact, for the majority of integration
scenarios, moving records in batch is easier to implement
and meets the business need. While real-time
integration can be a bit more complex (as it can involve
more complex user workflow and dependencies), there
are scenarios where real-time access is necessary and
more efficient.
Based on the cost savings from the iPaaS, SaaS Marketing
Company went forward with Scribe’s iPaaS approach.
4 – Meta Data Driven
ScrSaaS application users are likely to customize and configure
the functionality and data design of an application for their
particular need. Even so, the SaaS provider wants to encourage
developers in their ecosystem to develop solutions that can be
used across many customers. Our experience shows that SaaS
providersshouldprovidedynamicdiscoveryofeachcustomer’s
metadata at run-time when they design the API. Developers
can then surface those particular customizations in their
tools and set-up wizards to enable customers to quickly tailor
the integrated solution to their particular environment. This
metadata discovery goes beyond simply providing the objects
and fields in the customer’s environment; it should include the
relationships between objects, data types, and other attributes
(indexes, required, default or picklist values, etc.). By providing
this rich metadata discovery, a SaaS provider can leverage the
API to the fullest across a diverse customer base.
5 – CONSISTENCY AND
OBVIOUSNESS
The API should use standard and consistent naming
conventionsforobjects,attributes,fields,methods,actions,etc.
If it doesn’t, it can cause developers a great deal of confusion
and frustration. In essence, developers will be forced to learn
a new “language” each time they work with one of the SaaS
providers solutions. Or, worse still, they’ll end up investing
extra effort to re-code everything to resolve the confusion
created by the SaaS provider. In short, the API should “speaks
for itself” because this is one language barrier that can be a
deal breaker.
AnexampleofthisisCRUDsupport. TheAPIshouldsupportthe
full set of CRUD (create, read, update, delete) operations for all
relevant data objects within the SaaS application. This baseline
capability opens up a wide range of integration scenarios.
There may be specialized methods on some objects that go
beyond basic CRUD (converting a lead in a CRM system, for
example, or merging duplicate contact or company records)
that the SaaS provider may need to support. These methods
should be implemented generically across all objects so that
one consistent set of code can be utilized instead of having to
program each object on a one-off basis.
6 – SECURITY
It goes without saying that a great API must safeguard its users.
First and foremost, the API must consider authentication to
the API in the same way it considers access via the application
user interface. The API should have role-based security, i.e.,
giving API users the same rights and restrictions as application
users. The API should have thorough logging of user sessions
including who logged in, from what IP address, the actions they
took, etc. In this way, a SaaS provider can audit the behavior of
the API users and monitor for suspicious or malicious behavior
patterns. A great API may also offer delegated authentication
methods such as OAuth or Saml versus basic user name and
password authentication. This allows the application to be
accessed by another without requiring the target application
to know the user name and password credentials, dramatically
reducing the risk of those credentials being compromised.

7 – USER EXPERIENCE
Savvy software providers know that providing great documentation, best practices and tools is part of the complete offering.
There are many ways to provide this important support to your ecosystem of developers. For example, the API or the SaaS
provider might offer:
• Free, public and open access to the API.
• Great error handling is key for designing integrations using an API. When creating integrations, “generic” errors provide
little to no value. Providing via the API that the call failed because THIS specific field had THAT specific issue allows
someone to read the error, understand the problem and correct that process.
• Documentation and resources designed by developers especially for developers--resources that are heavy on
meaningful and relevant sample code. The SaaS provider should embrace the fact that developers like to figure things
out on their own.
• Access to free developer accounts with minimal restrictions. This allows developers to create, test, demonstrate and
support real-life customer scenarios.
• A very strong support site (and/or forums) where subject matter experts can share their knowledge and experience,
where internal and external developers can go to hold discussions and post questions and answers, etc.
• Certification or validation programs that help others leverage and promote the API’s integration capabilities.
Closing
With enterprises increasing the number of applications they have in use, APIs have become a critical enabler of data flow
across the enterprise and, therefore, of business agility. Those APIs that have the traits listed in this paper have the potential
to be great by enabling fast and easy data flow between applications. The quality of an application’s API, especially that API’s
integration capabilities, should be an important part of every application selection process moving forward. The quality of the
API’s integration capabilities is a critical factor in the long-term success of the SaaS application and will drive customer loyalty.
For SaaS providers, this means that they should treat the API’s integration capabilities as a core product capability and not an
afterthought of the total product offering. After all, the quality and functionality of every tool and feature layered on top of the
API depends on the quality of the API itself. A great API, therefore, enables the SaaS application to deliver more value to its users
and will establish the SaaS application as a mission critical component within the user’s technology infrastructure.

About Scribe Online
Scribe Online is a high performance, iPaaS that allows you
to rapidly integrate, replicate, or migrate data between your
critical business applications and data sources regardless of
whether they are run in the cloud, on premise or in a hosted
environment.
Available as a secure, multi-tenant and cloud-based service
Scribe Online offers built-in connectivity to a broad range of
business applications. Using Scribe Online’s intuitive graphical
interface, you can quickly and affordably create custom
connections between your marketing, sales, support, and
finance applications such as Salesforce, Microsoft® Dynamics
CRM, NetSuite, Oracle, HubSpot, Marketo, Eloqua, Silverpop,
Microsoft® Excel, Microsoft® SQL Server, MySQL, On24, and
Citrix®Go-to-Webinar.
As the experience of SaaS Marketing Company shows, Scribe
Online offers a number of long-term, strategic benefits vs.
custom coding to APIs. In particular, the platform’s benefits
span the entire integration lifecycle, including the design, build,
deploy, run, and, even commercialization stages. Key features
such as the “self documenting” graphical development
environment, a full debugger, collaboration features that allow
you to better manage integration projects, and a management
console for tracking all your integrations, bring you lifecycle
management benefits such as:
• Simplified API Management – A large library of business
applications are already integrated with Scribe Online
and that library is expanding continuously. The unique
characteristics of each application’s proprietary API are
exposed by Scribe Online in a single, consistent, easy-to-
use interface. So instead of learning dozens of APIs, you
can quickly create custom integrations between any of
these applications by simply working with Scribe Online’s
drag and drop mapping interfaces.
• Shorter deployment & Faster time to market –
Scribe Online offers out-of-the-box connectivity to
applications, drag and drop development capability,
reusable components, collaboration capabilities, and
solid debug tools that will allow you to create and deploy
integrations more quickly.
• Lower total cost of ownership – Regular Scribe updates
to critical application connectors, a self-documenting
development environment and reusable components
allow you to minimize long-term maintenance costs.
• Faster response to run-time issues – A unified
management console and well-documented, graphical
integrations from the product’s self-documenting
development environment, help you track all your
integrations, pinpoint run-time issues, and reduce debug
and down time.
• Staffing flexibility – Scribe Online’s design environment
and management tools are easy to use and easy to
learn allowing you to more easily change team member
responsibilities. You can switch the person responsible
for maintaining or updating the integrations and involve
people at different skill levels, such as analysts and
developers, to create, run, and maintain integrations.
• Agile customization of integrations – A capability to
integrate custom fields and deployment tools can help
you customize an integration for a specific business
group or customer. If you are selling integration services
or deploying integrations on behalf of different business
units, shortening this time can have a major impact on
your long term costs.
• Build Once, Connect to Many – If you need to integrate
with an application not currently connected to Scribe
Online, you can still say “Yes” much more readily because
you can utilize Scribe’s Connector Development Kit
(CDK), which includes source code, documentation, and
guidance, to easily connect that application to Scribe
Online as well. Once you have built that connector,
you can use Scribe Online’s drag-and-drop mapping
capabilities to connect that application to every other
application connected to Scribe Online.
To try Scribe Online, simply register for the free 15-day
trial and you are on your way. Free video help, user
guides, samples and examples are available with your
trial. Our concierge is ready to assist you with your trial
and to help you select the complementary connectors and
StarterPaks that are right for your business.

How to Spot a Great API

More Related Content

What's hot (20)

Viewers also liked (10)

Similar to How to Spot a Great API (20)

More from Scribe Software Corp. (20)

Recently uploaded (20)

How to Spot a Great API