What is the gold standard for website APIs? Twitter, Flickr, Facebook, etc.

Question

Seems like there are two categories of APIs for websites today.

1. APIs which allow the functionality of the site to be extended like Facebook, Myspace, etc. These APIs seem to be very diverse.

2. APIs which allow interaction with the existing site functionality like Twitter, Flickr, etc. These all claim to be REST based, but are in reality simply "data over HTTP".

If you were creating a website that allowed both functional extension and outside interaction, what existing APIs would you use as a reference model?

Answer 1

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/

Answer 2

It will depend on what your target audience is. If it is .net shops then soap is probably okay other wise focus on REST since it has a much lower bar of entry. From there look at website APIs that target the same people you would like to. This way your api will feel familiar.

Answer 3

I don't have any experience with the others, but even as it has evolved over the years, the Facebook API is still awful. It doesn't come anywhere near being a "gold standard." Rather, it is something people struggle through and grit their teeth because once they finally get it right, it can add a lot of value.

Answer 4

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 Spreadsheet API http://code.google.com/apis/spreadsheets/data/2.0/reference.html#SpreadsheetParameters
• Amazon S3 http://docs.amazonwebservices.com/AmazonS3/latest/API/
• Twitter http://apiwiki.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
• Digg http://digg.com/api/docs/overview
• 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)

Answer 5

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

Answer 6

Some APIs which are notably good:

• Last.FM http://www.last.fm/api (wonderful documentation)
• Github http://develop.github.com/ (pleasure to work with, well thought out)

Answer 7

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

Answer 8

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.

Answer 9

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.

Answer 10

Force (previously known as SalesForce) API: http://www.salesforce.com/us/developer/docs/api/index.htm

Answer 11

I think the best way to answer is to list the characteristics of good web APIs instead of citing examples. If you like Twitter/Facebook/etc APIs, what aspect of these APIs do you find attractive?

I'll take a first stab:

1. Well documented APIs, including constraints and usage policies. This enables rapid development with confidence, instead of second guessing what the parameters might mean, and what return values are.
2. Technology/language agnostic APIs. Good APIs should be easily usable, providing the same functionality, across a wide array of languages and platforms.
3. Well supported APIs. There are always bugs. Responsive maintainers result in more usable APIs
4. Layered API sets. When APIs are neatly layered, a wide range of developers can consume the pieces they need without needing to pull in extraneous layers. As a plus, it forces the creators to think hard about clean and componentized APIs.

Please add more to comments.

Answer 12

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.

Answer 13

AtomPub is the gold standard because it was designed by some of the brightest minds on the internet. You can't go too far wrong using iit as a basis. That is what google and msft does.

Answer 14

Had a similar question to this which didn't get much action, but thought it would be good to link to it.

http://stackoverflow.com/questions/775988/what-web-apis-would-you-most-want-to-replicate-or-are-the-most-popular

Answer 15

If I were designing a web api today for an existing web site, assuming the web site was well designed with respect to its proper usage of HTTP, I would use the existing web site as the design guideline.

Take Stack Overflow as an example, it has the entire URI space already mapped out. It has a complete set of interconnections defined between the different representations. Users of the site are already familiar with the site structure and therefore the API structure would already be familiar.

The only part that needs to change is the content of the representations, to eliminate all unnecessary markup. It would be necessary to add in a few extra templated links to allow for searches that are currently only accessible via javascript. For example, searching for a user is not easily discoverable via navigating because currently the link is built via javascript.

The really tricky decision is what media-type to use. You could use bare bones html with RDFa style metadata markup, or go wild and use the new Microdata format in Html5. Or, you could return a custom media type based on xml or Json. Something like application/vnd.stackoverflow.question+xml, etc. The custom media type makes versioning really easy, but it is less accessible to clients that were not designed to access StackOverflow directly. The custom types could be used in combination with Atom feeds which are mostly already there in StackOverflow,

Designing a web api is really no different than designing a website, other than the fact that you are delivering content that will be consumed by a program that is not a web browser.

What you don't want to do is create an Http based data access layer. That is just like showing your underwear to the world. The existing web site is optimized for all the common usage scenarios, many of the api access patterns are going to be similar, so reuse the "views" that have already been created. It may be necessary to add a few extra links here and there to make it a bit quicker for programs to get the data they want, but those can be added incrementally as the need arises.

Well written web sites are already very effective APIs for web browser clients, it is really not necessary to go back to the drawing board to support any other type of client. The API structure does not need to change, just the delivered content.