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

Answer 1

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 2

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 3

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 4

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

What web APIs would you most want to replicate or are the most popular?

Answer 5

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.

Answer 6

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.