Tag: API

ADWiki

ADWiki

Online documentation system for JavaScript projects that adhere to JSDoc API documentation format.  Includes:

  • Tools for parsing JSDoc blocks in the JavaScript files
  • Clean documentation website based on Twitter Bootstrap
  • Simple blog engine integrated with the site, where developers can commend and extend project documentation.

Requires Node.js and MySQL.

On using third-party APIs

In the few jobs I had, I was responsible for creating a new system and integrating it with some other systems.   The variety of the systems is pretty much irrelevant – anything from back office systems and CRMs to trading platforms and CMSs.  The common factor between them is the integration is often done through some form of the API.

The most important lesson I’ve learned while working with third-party APIs is this:

Never ever use a third-party API directly from your application.  Instead, create an abstraction layer between your application and third-party API.

This might seem like a bit of extra work, but, trust me, it’s not.  It will save you plenty of time and frustration.  Here are my reasons:

  1. Your own abstraction layer will help smooth out API’s edges.  If you are using third-party API, chances are, it feels weird at times.  It doesn’t matter what sets you off – function names, or required obvious parameters, or maybe the logic or order of calls that you have to make.  Instead of getting annoyed every time, you can abstract all that weirdness into a separate layer, which will probably not change all too often.  And your application coding will be more fun.
  2. Easier maintenance.  Even the best APIs change.  And when it happens, you don’t really want to go through all of your application and change all calls to the old version of the API.  Especially, if the updated version is not fully backward compatible.  Instead, you’d just rather update your API abstraction layer and be done with it.  And if you do, like you should, have unit tests covering your API abstraction layer, it will be trivial for you to see if you broke anything or not.
  3. Easier reuse and more control.  One of the biggest problems with third-party APIs is that you don’t control them.  Third-party introduces features, bugfixes, upgrades, and maintenance down-times whenever THEY want.  You rarely have much say in it.  When you have a layer in between the third-party API and your application, you have more control as to how all those things affect your application.
  4. Easier migration to another third-party API.  And you know that these things do happen.  You’ve been using one provider of the service, and now there is a better one.  If you were using first provider’s API directly from your application, you are pretty much in trouble now.  Going through the whole application replacing calls to the new API, with different set of parameters, data types, and return values, is a huge undertaking.  If only you had an abstraction layer, all you’d have to do now would be to change that instead. Sure, you might need to extend it a bit, or introduce changes to the currently used functionality.  But, from my experience, such changes would be much smaller and simpler (since you are working with your code on both ends).

 

ifttt – if this then that is awesome

If you are somehow involved with online tools, publishing, or social networks, then you should definitely check out ifttt.  It is an abbreviation for “if this then that” and it is the best thing since the invention of sliced bread. ifttt is an extremely easy, or perhaps even trivial, tool that helps you to connect and integrate web services.  Say, for example, that you use Google Reader and you want to publish your shared items to Twitter and Facebook and save starred items to Evernote or Delicious.  Can you do it? Sure, the solutions are out there.  But you will be solving each problem separately.  And good luck with technical support.  How about email or SMS integration?  Or Foursquare check-ins to Google Calendar?  You probably haven’t even thought of that…

iffft has a tonne of ready made solutions.  And even if there is something that you need which is not there, you have super easy tools to make it.  All you need to do is basically choose a trigger, like a new post in the blog, a new check-in, or a new shared item, and then choose an action like publish to Twitter or Facebook.  iffft will handle the gory technical details on its own.  If there is a need to authenticate a service, you don’t have to worry about it – it is already implemented.  If you don’t like some of the defaults, you can almost always change them – for example, how the descriptions of the Google Calendar events are formed from the Foursquare check-ins.

Emails, voice calls, and SMS are supported with loads of web services and notification systems.  The interface is very clean and simple.  And everything just works.  It’s been a long while since I saw something so well designed and implemented.  Give it a try, if not for the specific functionality, then just to have more experience with good systems.

Online identity, relationships, Google, and Social Graph API

Web Worker Daily covers the release of Google Social Graph API. These are pretty exciting news.

With so many websites to join, users must decide where to invest significant time in adding their same connections over and over. For developers, this means it is difficult to build successful web applications that hinge upon a critical mass of users for content and interaction. With the Social Graph API, developers can now utilize public connections their users have already created in other web services. It makes information about public connections between people easily available and useful.

Even better news are that one of the systems supported by Google is XFN – XHTML Friends Network. This is exactly the same XFN that you see mentioned in your WordPress administration. When you manage blogroll (links) of your site, you can attach different XFN attributes to each link. The screen looks something like this:

WordPress XFN editor

If your web site also uses one of the properly built WordPress themes, which has profile=”http://gmpg.org/xfn/11″ attribute set in the HEAD tag (see XFN join page for more information), then you are all set to go. Google will index XFN information from your site and will make it available via its Social Graph API.

It’s good to see Google stepping into this area. It brings a lot of public attention to a very useful area of our online lives. Soon, we’ll see more social tools and services like rubhub and Plaxo Pulse.