APIs Can Be a Pain

| by Boris Lublinsky Follow 1 Followers on Nov 23, 2011. Estimated reading time: 2 minutes |

A new blog post by Subbu Allamaraju discusses drawbacks of the current APIs implementations and ways to improve them.

According to Allamaraju, the following are the main problems that an API user is facing today:

The interface mismatch. Because APIs are created by a provider, they typically reflect the producer’s point of view - maximize use and reuse is the most common feature across all consumers APIs. This typically leads to creation of fairly granular APIs that allow every consumer to invoke any subset of these APIs in any sequence to fulfill his goals.

In this process, [the provider is] bound to tradeoff special requirements of consumers and try to stick to a common denominator. This creates a mismatch between what the consumer needs and what [the provider is] offering.

Writing client code is slow, repetitive and verbose. Using granular APIs generates multiple API calls results of which need to be aggregated.

Unless you got canned SDKs for these APIs, writing code to make 2*n HTTP requests and process the responses can take a while.

On top of that, for every API invocation, a client also needs to build requests and parse responses.

Getting enhancements from a provider slows one down. Because API providers support many consumers and work on their own schedules, that are often quite different from consumer’s schedule, it is typically hard to synchronized specific client’s requirements with provider’s schedule. Moreover, because providers are typically measured on API reuse, building one-off API for a specific consumer is typically hard to justify..

API requests are often chatty. Executing a chatty client, one making multiple HTTP calls, usually leads to both significant performance degradation and network over utilization. It is intuitively obvious that from both performance and network utilization point of view, using a less granular APIs is a better approach.

Consistent RESTful APIs don’t matter as much as we think. Although ideally it would be nice to see consistency across APIs implementation, the most important feature an API should provide, according to Allamaraju, is interoperability:

I would rather spend my time enabling interoperability than preaching for consistency.

Summarizing, Allamaraju noted:

The [main] client app’s challenges are aggregation, parallelization, and orchestration of forks and joins.

So how can this problem be solved? Allamaraju mentioned that eBay, my team has been working on a new platform to simplify use cases like the above:
  • Bring down number of lines of code to call APIs
  • Automatically orchestrate API calls as needed
  • Create new consumer-centric APIs that wrap existing producer-centric APIs
  • Cut down bandwitdh usage and latency

Allamaraju is not the only one suggesting such a platform. During QCon SF, Daniel Jacobson from NetFlix presented a similar solution currently implemented there.

The solution proposed by Allamaraju and Jacobson make perfect sense, but one has to wonder what is different from Enterprise Service Bus (ESB),that was touted as one of the main reasons of SOA’s failure? Or the problem was not ESB but its improper usage? Or was it a generally good pattern that now is getting a second chance?

Rate this Article

Adoption Stage

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Fix the title by Paulo Pinto

I thought this was an article about API design at the language level and actually it is only about REST APIs.

There are other types of APIs do you know?

Ease testing by Wong Franz

You will have a hard time in writing unit test if you don't add a layer for API calling.

Re: Fix the title by Bojan Antonovic

I'm sorry to say, but the blog poster and the author of the article have no clue about software development if they generalyze problems of REST APIs to problems of API theory at all!

Since when are REST APIs the only APIs? by Bojan Antonovic

The title of the article and of the blog suggest this. This is crap, and the conclusions are therefore crap. When the blog poster couldn't select the right title, then the article author should have fixed that.

REST + API = Oxymoron by Faisal Waris

Either you have REST or you have an API. You can't have both. The main point of REST is to avoid APIs.

Web API is probably a better term to use.

You need metadata to describe service interfaces (WSDL, oData, etc) without metadata and tooling you are wasting your precious time on plumbing code.

Recently I wrote two 'REST' clients where each client took about 3 days of effort to just get the plumbing code right. With something like WSDL, I would have been done in a few minutes.

WSDL-based interfaces suffer from the tightness that is inherent in XML Schema (i.e. it is hard to build open content schema models). Unfortunately, the world has wasted too much time in fruitless REST-vs-SOAP debates; we could have spent that energy building better Service API methods and tools.

Re: REST + API = Oxymoron by Jean-Jacques Dubray


Re: REST + API = Oxymoron by Paulo Suzart

Great comment! With, say, WSDL, we achieve productivity, consistency and interoperability. There is no time to waste on building your own client for an API. If providers distributes clients, are we back to EJB era?

I think that simple ways to build clients (as we do with WSDL) is the point.

Re: Fix the title by Subbu Allamaraju

Which part of "HTTP APIs" did you miss?

Re: Fix the title by Bojan Antonovic

The "HTTP" part. Without it, the sense is changed.

Re: REST + API = Oxymoron by Iyigun Cevik


Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

10 Discuss

Login to InfoQ to interact with what matters most to you.

Recover your password...


Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.


More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.


Stay up-to-date

Set up your notifications and don't miss out on content that matters to you