What is the gold standard for website APIs? Twitter, Flickr, Facebook, etc [closed]

Question

We're doing some research in this area ourselves. Not a lot out there in terms of "gold standard" for website API references.

The most common website APIs referenced are:

• Google APIs http://developers.google.com/api-client-library/java/apis
• Amazon S3 http://docs.amazonwebservices.com/AmazonS3/latest/API/
• Twitter https://dev.twitter.com/
• Facebook http://developers.facebook.com/
• LinkedIn http://developer.linkedin.com/index.jspa
• Delicious http://delicious.com/help/api
• YouTube http://www.youtube.com/dev
• Netflix http://developer.netflix.com/
• Sun Cloud API http://kenai.com/projects/suncloudapis/pages/Home

Another list here:

http://www.pingable.org/the-top-15-web-apis-for-your-site/

Someone recommended the book Restful Web Services as a good reference on this.

(please feel free to edit the above list to add other high profile websites with APIs)

How To Design A Good API and Why it Matters, a 60 minute Google tech talk by Joshua Bloch, is relevant.

Having worked with a few, I'll get right down to it

• Facebook

  • GOOD: clean and relatively consistent. Performs well and most things logically make sense. FQL is pretty neat. XML and JSON options. No pre-conception of response format other than what you really need
  • BAD: Changes often and without warning. 'official' api libraries are pretty atrocious. documentation of many calls are poor or missing. Non-standard authentication (some may call this good?)

• Myspace

  • GOOD: open standards (oAuth authentication, Opensocial endpoint)
  • BAD: often broken. Usage of oauth is very nonstandard and breaks most client libraries. official client libraries are terrible.

• Photobucket (disclaimer: I wrote the server side of the photobucket api)

  • GOOD: open standard authentication (oauth). xml, json, even php serialized array format as response parameters. faithful REST (get/put/delete/post on 'noun' urls).
  • BAD: not many client libraries. Architectural challenges with standard oauth libraries (users live on subdomains, calls must be made to subdomain, so url has to change).

• Twitter

  • GOOD: pretty consistent (though api vs search api has diffs). Good REST practice. OAuth authentication as well as supporting oldschool Basic.
  • BAD: error rate (pretty much consistent with rest of twitter though). Odd format of some return values (like their date format).

Ideal characteristics

• I'm not sold on 'strict' REST. PUT and DELETE cause problems in some client languages. GET and POST seem to be sufficient with appropriate 'verbs'. Also, RPC-like function names are OK with me as long as they're logical and maybe even part of the URI. In that case, object IDS still need to be very consistent though.
• Standard authentication/authorization. Basic/Digest can be ok, but I'm a fan of OpenID/oAuth (or WRAP if you want to get bleeding edge). Rolling your own means you have to explain 100% of it, and potentially write client libraries for everyone.
• Standard datatypes. Make sure you are consistent about your datatypes (either 'true' or 1, not some mix), and support the most generic standards. Datetime should be ISO8601. Geolocation should 'look like' GeoRSS, etc. You should be able to create an XSD/relaxNG/whatever strict validator for your return types. Expect the same standards from your inputs.
• Simple return structure. there's some benefit to XML-RPC/JSON-RPC in that you kinda know what you're getting back, but in any case, if I cant easily parse your return type with JSON or something like PHP's SimpleXML and essentially serialize it to a consistent hash, I'm going to be pissed.
• Support extension/expansion without breakage. Dont code yourself into a corner and make it hard to add to your API. Try to make good decisions up front that you wont be changing constantly.
• Documentation! Make sure its good, and explains everything. Even then it won't be good enough, so make sure you have dedicated time to work on it and a supporting forum or whatever to keep it up to date.

So that being said... something between Facebook and Twitter. Of course I'm partial to some of the stuff we have on Photobucket, but I also hate some of it.

It would seem to me that the documentation of the API is just as (or more) important than the actual design of the API.

Well written, simple documentation will make up for any design flaws. That's what I've learned after looking at the various links posted already. Specifically, Last.fm's documentation seems very good: easy to navigate and easy to understand.

Last.fm's api continues to be one of the most well maintained apis on the net. It's also been around longer than most, because it started out basically as just that.

http://www.last.fm/api

Regarding Jeff's list of big APIs: I am pretty sure that common does not mean "Gold Standard".

No need to keep a manual list of widespread API. To get a list check out http://www.programmableweb.com/apis/directory/1?sort=mashups .

Since I like REST as loose standard, I'd say that an API is "Golden" when it makes sense and is intuitive.

• Twitter ( http://apiwiki.twitter.com/ ),
• Github ( http://develop.github.com/ ) and
• Last.FM ( http://www.last.fm/api )

… all make the most sense for me and are well thought out (as Brian already pointed out).

In my current daily work I also work a lot with OpenSocial, where URIs feel very natural but also extend the REST standard in its own way.

If you like it strict and safe, use SOAP.

I would check out OpenSocial, a movement to create an API Standard for social network sices. They use REST for this and have a 'user' centric approach. But this is a very well documented approach which might help for even a site that is not totally Social based. If you are looking for some internal code implementations look at Drupals hook system and Wordpress.

http://code.google.com/apis/opensocial/