APIs Can Be a Pain

Posted by Boris Lublinsky on Nov 23, 2011

Sections

Architecture & Design,

Development

Topics

ESB ,

SOA ,

REST ,

API ,

Architecture ,

Enterprise Architecture ,

Programming

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

...at 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?

1. Back to top

   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?

   Reply

2. Back to top

   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.

   Reply

3. Back to top

   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!

   Reply

4. Back to top

   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.

   Reply

5. Back to top

   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.

   Reply

6. Back to top

   Re: REST + API = Oxymoron

   by Jean-Jacques Dubray

   +1

   Reply

7. Back to top

   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.

   Reply

8. Back to top

   Re: Fix the title

   by Subbu Allamaraju

   Which part of "HTTP APIs" did you miss?

   Reply

9. Back to top

   Re: Fix the title

   by Bojan Antonovic

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

   Reply

10. Back to top

    Re: REST + API = Oxymoron

    by Iyigun Cevik

    +1

    Reply