Recently, I got to work on a project that involved communicating with three of the main Social Media sites. Twitter, Facebook and LinkedIn. The task sounded fairly straightforward, all I needed to do was add a feature to Umbraco to allow you to share a page with one or more accounts on each of those networks.
Not too complicated I think to myself. All three platforms are big, and popular, so there must be decent APIs and SDKs available! So I did the easy parts, set up my config files, event handlers, menu items and dialogs, all good so far. So next up, I sit down to implement the first network.
Twitter
Twitter is the big one. Its effectively a hosted service,
with a basic UI, that other people interact with and pipe data to
and from. Consequently, their API is fantastic. Its easy to use,
extremely well documented, and has more SDKs and libraries in every
conceivable language than any other system I've worked with.
Consequently it took less than two hours to find a decent SDK (I
used the excellent TweetSharp),
work out what API calls I needed to make, set up an App in Twitter,
authorise it and get it all up an running. Its a great example of a
service provider going out of their way to make you want to use
their API. Hell, Twitter pretty much stands around on street
corners flashing its goodies at you screaming for you to use its
API.
Facebook
Next up was Facebook. Another heavy hitter, these guys
also have a fairly comprehensive API, lots of documentation, and
loads of SDKs and toolkits. The only problem is that they change
their API a fair bit, so a lot of the information on the web can be
out of date (as well as some of the official documentation). This
caused me a bit of pain on a few occasions where I found out I was
calling deprecated API methods and so forth. On the whole though,
the whole process only took a couple of hours or so longer than
Twitter, and some of that was down to Facebook being fussier about
setting up Apps. I used the excellent FacebookWeb
SDK in the end to do all the grunt work.
LinkedIn
And finally, the new kid in town. These guys have an API,
its not bad, but working with it isn't easy, especially if you use
.Net. There's only one 3rd party Toolkit, which forces you to
inherit from basepages (which wasn't any good for my code), and the
documentation is OK, but REALLY badly laid out. In fact I'd go as
far as to say it was excruciatingly painful trying to get working
code for LinkedIn. As the 3rd party toolkit didn't meet my needs, I
ended up rolling my own code based on oAuth and some code I found
buried on the support forum. It took me about a day to get it up
and running, not helped by the fact that the example in C# I found
for updating statuses was out of date.
The difference between the three is quite marked. You can see why everyone and their dog does Twitter integration, it's so EASY. Even Facebook, while slightly fiddlier, doesn't present too much of a challenge for most tasks. But LinkedIn is a nightmare. Things look better if you're a Ruby or PHP person, as better toolkits are available. But still, if you're going to release an API for your system, here are a few tips that will make us developers like you more, and should hopefully result in better takeup of your system with integrators:
- Document everything thoroughly, and for God's sake update the docs if the API changes!
- Have example code in as many of the major languages as possible. Don't have inhouse .Net/TCL/Python folks? Hire a freelancer, or sponsor someone in your dev community to do it. Developers love example code. Also, the updates thing. No one likes going through code examples to find out they don't work because the API was updated and no one updated the examples.
- Make it easy for us developers to create SDKs/Toolkits for your API. We love doing that, and most of us will share that code with others too!
- Make you API make sense. If your methods have human readable parameter names, we can figure out whats going on better than having short/obscure/gibberish ones.
- As above, but for method calls. Make sure they make sense.
- Don't make us use the API to find out the information we need to use the API. If there's a web interface for your app, give us a way of getting ids etc, don't make us write code who's sole purpose is to get the ids/whatever I need to use your API.