TM TM

CONNECT ONCE,
CONNECT ONCE,INTEGRATE EVERYWHERE
INTEGRATE EVERYWHERE

Top 10 Common API Pitfalls

By Rick Nucci, CTO Boomi

TABLE OF CONTENTS
Introduction 1
Introduction
Top 10 Common API Pitfalls 1
A robust application programming interface (API) has become essential for today’s
successful SaaS independent software vendors (ISVs). As a SaaS vendor, you Conclusion 4
should expect that a majority of your customers are going to require interoperability
with other SaaS applications, web services, and legacy systems. As demonstrated
by internet pioneers Google, Amazon, and Facebook, an open application strategy
facilitates deeper customer usage and enables new revenue streams. Integration
is critical for SaaS vendors, and developing a reliable API strategy is the first step
toward achieving that goal.

Unfortunately, many ISVs still treat their API as an afterthought or merely a

“checkbox” on their project list rather than a core feature of their solution. As a
result, APIs are not well designed or properly built and wind up costing both the
vendor and its customers tens of thousands of dollars in ongoing maintenance
due to infrastructure costs and the drain on engineering resources. After reviewing
hundreds of actual SaaS APIs, many up to par and others distinctly subpar, it is
clear that there are a number of common mistakes made when developing an API.
Fortunately, each of them can be easily remedied by following best practices.

Top 10 Common API Pitfalls

1. Exposing operations instead of objects
Impact: Bloated call proliferation. By exposing operations, the number of calls
your API has to support will balloon up to 4-5 x the number of objects in your
application. What’s more, if more than one resource is building your API, there is
a bad habit of inconsistent naming conventions, i.e. “addCustomer” and
“insertItem” will exist in the same API.
Remedy: Consider schemas for each object you support, and a common set
of actions that can be performed against those objects, i.e. add(), update(),
delete(), query(), and of course upsert(). Don’t forget about this often overlooked
action, it will significantly reduce the IO against your API because the ‘check
for this, then do this’ logic is inside your API tier vs. invoked by the client. This
 TM
CONNECT ONCE, INTEGRATE EVERYWHERE

forces all of your developers to follow a consistent set of actions and think about
the implications of those actions against a particular object versus designing “Companies are more
arbitrary actions against their objects in a vacuum. Following this advice will also likely to embrace SaaS
drastically improve the readability of your API.
if they can bypass any
2. Assuming a WSDL contains everything necessary to describe integration issues with
your API
Impact: To support the dynamic nature of your API, you either end up doing a
their core business
blended WSDL/meta data API combination, or you contort and stretch the limits applications.”
of your WSDL such that most web service toolkits cannot support it.
Remedy: Keep in mind that WSDL was designed under the assumption
that your API call was static, and not multi-tenant. The reality is the majority
Mary Hayes Weier ,
of your customers are probably customizing their tenant of your app, and Information Week
those customizations need to appear in real time in your API. This is, from an
integration perspective, one of the huge strengths SaaS apps have over their
on-premise enterprise competitors. In the on-premise world, the APIs of those
applications were either non-existent or at best completely disconnected from
any customizations made to the application itself. Consider offering explicit
metadata descriptor calls and in these calls return both your base schema for a
given object along with any customizations made by the customer back to the
user. Try denoting the custom fields with a consistent naming convention, or a
dedicated section within each object.

3. Developing a single version of your API which changes with

each release of your SaaS application
Impact: Your customers get on the “API treadmill” which requires that they
repeatedly have to test their integrations with each release of your application.
This will inevitably lead to push back from the customer base which may result in
pressure to reduce the frequency of your product releases.
Remedy: Think of your API as a contract between you and your customer.
Once you release it, that specific version needs a SLA guaranteeing
compatibility to it for some extensive period of time (years). As you release new
versions of your application, version your API also. You can include the version
number of the API as part of any URL request made against it.

4. Never batching or throttling the results of query calls

against your API
Impact: Your application performance degrades, resulting in a substandard
experience for your API users as well as your web users. You will also likely face
unexpected increases in infrastructure costs to support unpredictable demands
on your usage.
Remedy: Put throttling in front of all of your API calls. There are specialists in
this area, such as Mashery, that can proxy all of your API calls and enforce this
behavior for you. Typically, experts recommend a time based throttle such as

P2
 TM
CONNECT ONCE, INTEGRATE EVERYWHERE

X-thousand calls per hour/day. You can also consider charging for additional
throttling needs. However, this should not be viewed as a margin-based revenue
source and instead should be viewed as a cost-protection revenue source. By
charging a premium, you can offset the cost of the existing infrastructure needed
to support their requirements. Fortunately, this is also becoming less of an issue
due to the advent of elastic computing capabilities a number of cloud providers
now offer because your API infrastructure can expand and contract inline
with demands. Additionally, for any API call that can return an unpredictable
number of results, consider returning those results in pages or groups of some
reasonable number, along with a marker that your caller can use to iterate your
pages as they see fit.

5. Maintaining separate schemas for adding, updating, or

removing your Customer object
Impact: Creates the perception of inconsistency and complexity in your API.
A Customer, Product, Employee, Invoice, etc. is what it is, regardless if you are
adding it, changing it, or removing it.
Remedy: Have a single schema for each object type. If you do not allow certain
fields to be changed in your application once a record has been added, then
either throw an error if the users pass in a value for this field (ideal) or ignore the
contents of any field that cannot be modified.

6. Forcing the user to specify the data type of fields being

passed into your API
Impact: You are creating an unnecessary dependency on documentation.
And the problem carries forward not just to the initial user of the API, but in the
ongoing changes to the underlying schemas that result from customization and
product enhancements.
Remedy: Provide the most relaxed data type restrictions possible and
clearly type fields that restrict format patterns, such as a date/time field. An
overarching goal when designing your API is to have to write the least amount of
documentation possible and instead expose maximum metadata about your API
through the use of explicit descriptor calls.

7. Using session-based security in your API

Impact: By forcing a session to be created and re-used, things like long running
queries need to be contemplated and they are typically not, resulting in sessions
being terminated mid-transaction.
Remedy: Use a standardized sessionless security model like HTTP basic
authentication or WS-Security with Username/Password token. Try to avoid
implementing a proprietary authentication model like username/password in
the SOAP headers or username/password in the body of the data being sent to
the application, as this is not discoverable programmatically. Using sessionless
security is a convenience for the user as well as provides easier scalability on
the server side. This allows requests from the user to be routed to any server
in the data center without needing to share sessions between them. Also, by

P3
 TM
CONNECT ONCE, INTEGRATE EVERYWHERE

avoiding any login orchestration it is easier to get other websites to access your
API so they can do mashups.

8. Not providing a way for your user to know when a record

was modified
Impact: Your users cannot capture “deltas” or changes to your data over time.
This forces them to do bulk extracts out of your application, causing significant
inefficiencies and detrimental performance impacts on your application.
Remedy: Modification tracking is critical any time data in your application
needs to be synchronized with another application. This is almost always a
requirement with master data, i.e. Customer, Product, Employee, Vendor, etc.,
as this information is core to your customers’ business and will almost always
be represented across all of the key applications they use. By exposing when a
record was changed, and who changed it, external processes can capture this
information and only extract the changes since the last sync vs. a full extract.

9. Charging extra for your API and not including it for free as
part of your offering
Impact: An API is never viewed as an “add on” feature by your customer, it
is viewed as a “get in the game” feature. In most cases it is needed for parity
against your competition, not differentiation. As a result of this expectation, you
may end up in an unnecessary and risky negotiation with your prospects.
Remedy: Make your API free with every edition of your offering. Tout your
commitment to openness and encourage your users to explore your API, even
during their trial period. You will earn loyalty points with your customer and the
message of confidence you exude with this positioning will make you friend vs.
foe in the developer community.

10. Getting caught without an API strategy

Impact: You are likely losing deals to your competitors and worst case you
are not even aware that the lack of API is the reason. You will be perceived as
“legacy” and “closed” and “proprietary”.
Remedy: Beyond the obvious suggestion which is to “build an API!” and from
the outset, treat your API as a core part of your product and not an assignment
you give the summer intern. Ensure that the API is represented by product
management, and put strong resources on the engineering of that API. Consider
this: salesforce.com reports that their API gets more traffic than their application!

CONCLUSION
Unlike the enterprise application era when applications were kept closed and
proprietary, the success of today’s SaaS applications depend upon being open and
interoperable. ISVs should view their APIs as not just a means of integration but in
fact as a way to syndicate their capabilities to a much broader audience—a channel

P4
 TM
CONNECT ONCE, INTEGRATE EVERYWHERE

to market as it were. As such, implementing a well conceived and well designed API
is arguably as paramount to the success of your business as developing the base
application itself. Following the guidelines above should help in maximizing your
success as you design, build and implement your API.

Rick Nucci – Co-Founder & Chief Technology Officer

Rick is the Co-founder and CTO of Boomi where is responsible for product management and engi-
neering. He is considered an industry expert on SaaS & Cloud integration, multi-tenant architecture,
and API design and best practices. Boomi has a patent pending for Rick’s innovative Atom technology
that powers Boomi AtomSphere, the company’s software-as-a-service offering. In his role at Boomi,
Rick is constantly engaged with customers and partners to ensure alignment between business needs
and Boomi’s product strategy.

Prior to founding Boomi, Rick worked for EXE Technologies, a market leading supply chain execution
software company, in the areas of product development and implementation. It was in this role that
Nucci learned first-hand the cost and complexity of integrating disparate applications and business
partners. With over 10 years of experience in application and data integration, Rick applies this experi-
ence to deliver the company’s integration solutions.

Rick frequently speaks on these topics at industry and business events nationwide including SIIA On-
Demand, Interop, and GlueCon.

Boomi Corporate Headquarters

Address: 801 Cassatt Road, Suite 120,
Berwyn, PA 19312
Tel: (800) 732-3602
Email: info@boomi.com

West Coast Office

Address: 473 Jackson St., 3 rd Floor
San Francisco, CA 94111
Tel: (800) 732-3602
Email: info@boomi.com

Boomi is the market-leading provider of on-demand integration technology and the creator of
AtomSphere, the industry’s first integration platform-as-a-service. AtomSphere connects providers
and consumers of SaaS and on-premise applications via a pure SaaS integration platform that
does not require software or appliances. ISVs and businesses alike benefit by connecting to the
industry’s largest network of SaaS, PaaS, on-premise and cloud computing environments in
a seamless and fully self-service model. Leading SaaS players rely on AtomSphere to accelerate
time to market, increase sales, and eliminate the headaches associated with integration.

For more information about Boomi, visit www.boomi.com.