Mega-man and software development

What can Mega-man teach us about designing APIs that are built to last

One major difference between tools (such as APIs) and products is the end-user. The end-user for products is generally through a consumer-internet channel to the pragmatic folks. Technologies on the other hand are accessed by developers and other power-users who use them to develop products that in turn reach end-users in a different market-segment.

I watched an amazing video in a post by Jeff Attwood (@codinghorror) that talked about the need for an intro stage to make process of understanding a tool and it’s capabilities much easier. I particularly want to focus on APIs here because of the recent populrity and the whole idea of API-fy everything1

Once a startup makes a product and become successful, a lot of people want to use their products. An obvious conclusion, but a slightly less obvious one is that a lot of developers also become interested in the idea of what makes this product tick. More importantly, often times the companies realize that other hobbyist or developers can create really cool new projects by using their infrastructure. The company can’t reveal it’s secret sauce however very often they will write some code that works around this issue and the idea is called a blackbox abstraction:

This concept is represented by the above figure: The blackbox interacts with the secret sauce but we can’t really see into it. It takes an input and produces an output. An API is much the same way, it has some very nicely defined functions and features that we can use to access the blackbox for results.

Let me give an example of this: NPR has amazing news all the time in it’s various different sections. Say you wanted to look up news. But you have requirements: You want to look up all the stories after a certain date containing a phrase in the headline. Or say stories published every Tuesday in your favorite section. You can of course just google every single story that contains a phrase that you want, or manually collect links to certain dates. But there’s a limit to it. Let’s do this automatically, and this is where an API comes in. The API programatically allows one to access stories which are nothing but text. The programmability adds the logic to it so that a developer can create something meaningful out of the stories. Going back to the blackbox: You don’t need to know anything about how the API works, as long as you have access to the functions and features of the API, you can take a product (like NPR’s stories) and do something automatic and meaningful with it.

As one can imagine, based on this idea, a lot of companies are pushing for creating APIs for their products and their development is expensive and time-consuming. What’s important is that when a developer tries out the API, it needs to be easier for them to play with it. Including code-samples might not cut it anymore. Include links to talks you’ve given on it or a tutorial that goes step by step to walk them through and lead the developers down the right alley. The best sense of using an API for a developer is to create something out of it, and fast. That will leave the devlopers wanting to use the API all the more. This is critical for data and healthcare, as we have more medical and fitness devices, having these APIs allows developers to come up with use-cases that the company might not have thought of.

Jeff mentions the idea of an intro-stage in megaman. The intro-stage teaches you basically everything you need to know to play the game. If you don’t know a step, the rest of the game is designed to be intuitive so that you can learn “on-the-go”. That makes the developer-experience absolutely delightful and even if your API doesn’t provide a lot of features, it will certainly attract more developers. I really encourage the reader to watch the video related to this post:

  1. There has been a huge push to create APIs for all the products and services out there. This allows developers to manipulate and incorporate non-programmatic content into programmable logic. The push in the area is to be able to manipulate every source of information in a similar meaningful way to create better products that can then utilize those APIs to provide great content to the end-user.