Is it Difficult to Write REST Clients?

The headline to this story his misleading. Adam never mentions the word REST in the first story, and only uses the word REST once in another story and even then only in a different context: "Differing standards (REST v SOAP v XML-RPC, XML v JSON v POST, versioning v not, etc.)"

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.

John,

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.

Now, if you prefer we could also discuss how people write REST clients using a Human Readable Documentation vs Machine Readable, how the unabated extensibility of HTTP is helping that process or how developer friendly OAuth is. I almost forgot, how a new version of the API impacts existing clients. That would be a very interesting set of questions to answer, but maybe you consider them to be flame bait too.

C'mon. You answered two question with two totally different questions.

I'm not playing games. I am asking for responsible, neutral reporting over sensationalism.

There is no need for suggesting what else I consider flame bait.

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."

John,

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.

Thanks. I better understand where you are coming from now.

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?

I don't want to run into the debate of what people call REST. Subbu has talked about it at the last RESTfest (www.subbu.org/blog/2011/08/measuring-rest-2).

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.

So let us say that I have an article entitled "Is It Difficult To Write SOAP Clients?". Suppose this article uses non-compliant implementations (that never the less claim to be SOAP) as examples to demonstrate that they are, in fact, difficult.

Is it your assertion that I have no obligation to verify that my examples are valid?

Can any one claim that the industry is not calling Facebook, Google, or Twitter APIs "REST APIs"?

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?

Facebook has very weak incentives to do a good job of exposing their data to third parties. A really good API would defeat their business plan of keeping the data on their servers and as their property.

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.

I am actually quite surprised at this argument, the Facebook Graph API was touted as one of the best implementation of REST: www.subbu.org/blog/2010/04/uncomplicated-hyperm...

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.

Can you please speak through your personal experiences rather than linking me to a blog post where the author shows zero technical examples of what he/she is saying?

Thanks.

Breaking an API due to lack of handling versions have very little to do with SOAP, REST or hypermedia. It is entirely possible to have a bad versioning approach with any software, no matter how it is developed. It is equally possible to have a good versioning approach with both REST and SOAP.

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?