[bryanh]

All API's are not made equal. Some may not be around in 2 years, some 10 years, but in the time you are forced to work with some of them, you might lose your sanity.

I'm working with pretty much every type of API through my startup Zapier.com and some of these API's I wouldn't wish upon anyone except maybe the deeply masochistic coder. They suck. I suppose that's good for us. However, we aggregate data from many dozens of APIs for the end user, so losing an unpopular service's API here or there doesn't hurt us in the least.

While I've got an API pedestal and a crowd of developers: please no SOAP or XML. And do NOT go off the OAuth spec. Bad documentation is the gravest of sins, which can mean lack of examples or, worse, out of date info/examples.

Good APIs: Github, Wufoo, Strip. All of them are more or less self documenting, use JSON, and RESTful. The docs are awesome. A joy. In and out.

Bad (or just annoying) APIs: Salesforce, 37signals, Google Contacts and co, Docusign... While they work, you'll struggle every inch of the way to make the simplest things happen. XML (or some derivative) and SOAP. No thanks.

[6ren]

You don't think there's a benefit to XML formats that have an XML Schema, so you can do automatic data-binding (at least in Java, with JAXB)?

There are also many visual XML mappers (mapforce, biztalk mapper, stylus studio, IBM and Oracle integration products)... but truly, these are enterprise-expensive tools which I think are only used in the enterprise (with its more complex data and, some say, unnecessary corporate inflexibility).

While it's true that disruptive tools tend to start at the bottom (e.g. with startups) and bubble up, the complex data needs of the enterprise have to be addressed in some way, either by sticking with conventional tools, or the new tools growing in ability. The common consensus seems to be that if JSON's ecosystem developed a schema language, a "JSLT" etc etc, it would be just as ugly as the XML ecosystem (i.e. ugliness is partly due to irreducible complexity) ... and we already have one.

I wonder if the technology development path might be similar to Twitter, iterating quickly with agile, featherweight Ruby, then switching to Java only when scaling demanded a heavyweight solution: start with light JSON when the needs are straightforward; move to XML when complexity demands a heavy solution. For many wildly successful startups, that might not happen, and JSON might remain perfectly fine; just as many startups stay with Ruby.

[bryanh]

I think you make a good point, there are definitely complex situations that call for Java-esque and enterprisey tools. However, having a simple solution often trumps complex solutions when you just want to "get things done"™.

I suppose it boils back down to the most appropriate tool. Are you selling to enterprises? Use SOAP. Everyone else? Use REST/JSON.

[6ren]

Yep, as simple as possible, no simpler. (NoSQL is another example)

I think a central source, like a database, needs to cater for every possible use in general (which the relational model does); but if you're doing something very specific, it's crazy wasteful to do it with full generality.

I am curious if someone can work out how to make a simple API that is also fully general (I think it has to be equivalent to the relational model - but it's early days yet).

[brlewis]

I mostly agree with you, but think XML is OK for a read-only API if your data fits RSS or Atom syndication.

[bryanh]

Sure, its okay. But compared to the ease of JSON...