Is it Difficult to Write REST Clients?
- Share
-
- |
Read later
My Reading List
Adam DuVander, from the Programmable Web,reported last week on a survey of API experiences which raised some of the largest problems developers encounter in consuming Web APIs, including the most popular APIs.
The Facebook API was mentioned far and away more than any other in long-form answers to questions about headaches, horror stories and other issues while integrating with APIs. Also mentioned often were Google APIs and the Twitter API. While it should be noted that all three are also among the most popular for developers, there are lessons to be learned in mining the results of this survey put out to Hacker News readers.
Trove, who ran the survey to evaluate the cost of API integration and maintenance, reported on its blog that:
[API providers] are not serving their developers well. There’s bad documentation. There are problems with services like OAuth. APIs randomly change without warning. And there’s nothing even resembling industry standards, just best practices that everyone finds a way around. As developers, we build our livelihoods on these APIs, and we deserve better.
[The] Biggest Headaches with API Integrations: Well, no surprise for us, but here’s a quick list of your major complaints:
- Poor documentation (how you loathe poor documentation)
- OAuth (oh wow, do you hate OAuth)
- Poor error handling
- Lack of example code
- Lack of test environments
- Lack of standardized libraries across languages
- APIs that change/break frequently (huge shout out to Facebook here, like you’re surprised)
- Normalizing data to match internal data structures
- Line between use and abuse
- Arbitrary throttling (differences between services)
- Differing standards (REST v SOAP v XML-RPC, XML v JSON v POST, versioning v not, etc.)
- Getting services to talk to a dev machine behind a firewall
Who Makes Your Life Easier: In general… No one! However, honorable mentions go to Mashery and Apigee.
In this context, Trove did find surprising though that developers felt maintenance improved with time.
One of our biggest assumptions was that the maintenance overhead for integrating services would get worse year after year... However, the survey results say the opposite.
They remain cautious about the interpretation of that answer and they plan on running another survey to better understand the meaning of the current one.
Slanted headline
by
john zabroski
Please, there is no need for flame bait headlines.
As far as Facebook, Google, and Twitter go... what do they have to do with the Web? Moreover, how can anyone reasonably compare their APIs to business-to-business needs? It is a category error.
Re: Slanted headline
by
Jean-Jacques Dubray
could you please let me know how many Web Services (SOAP based) use OAuth? and also how many developers use the SOAP Facebook, Twitter and Google Web Services? If the answer if less than 1% (possibly even zero), I am not sure the title is misleading.
Re: Slanted headline
by
Jean-Jacques Dubray
Re: Slanted headline
by
john zabroski
I'm not playing games. I am asking for responsible, neutral reporting over sensationalism.
Re: Slanted headline
by
john zabroski
Bottom line: By titling this story "Is it difficult to write REST clients?" you are planting the idea in people's minds that they might want to reconsider writing REST services. Instead, you should be planting the idea in people's minds that it costs them customers.
Trove's statistics are meaningless to most financial people/number crunchers. If Trove can find a relationship between quality APIs and customer loyalty, then number crunchers will pay attention and tides will rise. The real storyline here is that Facebook's APIs suck, but guess what, everyone uses them and has to use them.
On the other hand, when looking for business-to-business APIs and stuff to mashup into B2B apps, who has the most users does NOT play a role. There is a reality distortion of social media put in place by looking at services of Google, Facebook and Twitter. Say I want an address standardization API, a common B2B need. What I really care about is reliability, cost, terms, etc. There's almost nothing coding related.
Occasionally, there are times when coding concerns overlap with the "what I really care about" concerns. One example is APIs that don't have a Quota API for dynamically establishing the quota on, say, a file upload, or how many more requests you can make before going up a payment plan. Amazon S3 is a good example. I complained to them a long time ago how they have PDFs that say you can have X numbers of buckets, etc. but no web service that you can query. So you are stuck putting some arbitrary constant in your application. What happens if that changes? Well, your app can break.
Why do people write apps this way? Well, most people reason by analogy and naturally assume consistency. If "S3" is called "REST API", and they are told to build a "REST API", then the path of least resistance is to just try to copy some very narrow ideas and not take into account the context in which they were made. Sometimes, the designers took no context into consideration at all. And many are incapable of judging a good solution from a bad solution, because often there are subtle differences between good and bad. We saw this with OOP: Fragile Base Classes, SOLID Principles, etc. As Alan Kay once said about pop cultures:
"Computing spread out much, much faster than educating unsophisticated people can happen. In the last 25 years or so, we actually got something like a pop culture, similar to what happened when television came on the scene and some of its inventors thought it would be a way of getting Shakespeare to the masses. But they forgot that you have to be more sophisticated and have more perspective to understand Shakespeare. What television was able to do was to capture people as they were. So I think the lack of a real computer science today, and the lack of real software engineering today, is partly due to this pop culture."
Re: Slanted headline
by
Jean-Jacques Dubray
I appreciate your argument. We'll have to agree to disagree on the conclusion since no complaints surfaced in the survey on using a contract such as WSDL or code generators such as WSDL2Java. All the complaints had a common denominator that the industry generally calls REST (writing clients by hand, using human readable documentation, most REST APIs I ran into have no sample client code, specially in different languages ...). If you don't want to call it REST, again, let's agree to disagree, but this is what most people call REST.
Re: Slanted headline
by
john zabroski
What most people call REST is clearly not so, since they must resort to out-of-band information. When the out-of-band information changes (IMPLICIT contracts change), their clients break.
That is certainly not the Web.
Agree or disagree?
Re: Slanted headline
by
Jean-Jacques Dubray
All I am saying (and have been saying) is that we need machine readable contracts for several reason including versioning this is the most important thing to focus in a Service Oriented Architecture. Without proper versioning, you break clients often.
Re: Slanted headline
by
Rob Scott
Is it your assertion that I have no obligation to verify that my examples are valid?
Re: Slanted headline
by
Jean-Jacques Dubray
What is "non-compliant" REST? The entire industry calls what they are doing "REST"? I would be curious to know what is non compliant about OAuth, what is non-compliant about Facebook, Google or Twitter APIs?
Re: Slanted headline
by
john zabroski
Facebook, period, is a very poor comparison, unless we are discussing the art of carefully exposing information to create a third party ecosystem while still controlling the platform.
Re: Slanted headline
by
Jean-Jacques Dubray
If Subbu says about it: "Hypermedia does not have to be complicated – and Facebook just proves it." what is there in the Graph API that is not RESTful? It actually looks like one of the better RESTful API I have seen.
Re: Slanted headline
by
john zabroski
Thanks.
Re: Slanted headline
by
Herbjörn Wilhelmsen
Also, if almost everybody is using one API and almost no-one is using the other API where would you expect to get more complaints?
Educational Content
Writing Usable APIs in Practice
Giovanni Asproni May 19, 2013
Hello stranger!
You need to Register an InfoQ account 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