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

Answer 1

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.