[occi-wg] The Top 10 Most Common API Pitfalls

[Sam Johnston]

Morning all,

An interesting article by Boomi's CTO just popped up on TechCrunch that
touches on many of the ways one can go wrong when creating an API. We're
doing well with each of these points, except perhaps rate limiting which
doesn't sound like a core concern anyway (rather an extension).

Sam

The Top 10 Most Common API
Pitfalls<http://www.techcrunchit.com/2009/11/08/the-top-10-most-common-api-pitfalls/>

*This is post was written by TecCrunchIT guest author Rick
Nucci,<http://www.crunchbase.com/person/rick-nucci> the
Co-founder and CTO of enterprise integration technology company
Boomi.<http://www.crunchbase.com/company/boomi>Prior
to forming Boomi Inc., Rick worked for EXE Technologies.*

A robust application programming interface (API) has become essential for
today’s successful SaaS independent software vendors (ISVs). As a SaaS
vendor, you 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.

*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 they ‘check for this, then do this’ logic is inside your API tier
vs. invoked by the client. This 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 arbitrary actions against their
objects in a vacuum. Following this advice will also drastically improve the
readability of your API.

*2. Assuming a WSDL contains everything necessary to describe your API*

*Impact:* To support the dynamic nature of your API, you either end up doing
a blended WSDL/meta data API combination, or you contort and stretch the
limits 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 of
your customers are probably customizing their tenant of your app, and 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 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 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 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.ogf.org/pipermail/occi-wg/attachments/20091109/25a64b82/attachment.html