I happy to announce here that I have connected with a new opportunity that represents all of the things I’ve been wanting to do next. I am very excited to become CTO at outside.in, which has been my favorite NYC startup for a while now. Here’s why:

  • I don’t know what Web x.0 means anymore. But while we figure that out, the holy grail for everyday Web use is filtering and organization of data of interest, along axes that make sense. Outside.in has nailed this from day 1, choosing geographical proximity as that axis.
  • The OI platform stack has to scale massively. In prior roles I’ve sometimes said that the technology I’m helping build has scaled beyond “consumer app numbers.” OI already has those numbers, and needs to cleverly grow fast as an aggregator, publisher, API provider, and Web app. This is my idea of fun.
  • The news business is shifting even as I write this. More agile, community-centric news delivery and filtering are already here, and traditional new businesses are adapting or facing extinction. OI offers  Big News and all authors, small and large, the platform they will embrace for distribution and monetization of local information. In short, our timing is absolutely perfect.
  • Technologies in the worlds of Natural Language Processing and Semantics are coming of age, and OI is making practical use of them in very creative ways. I may even have a few ideas about this up my sleeve.
  • Amazing team! Founders Steven Johnson, John Geraci, and Cory Forsyth created an incredible startup energy, and our CEO Mark Josephson is taking that a few notches further. The dedication, smarts, and creativity of this group of people is awesome.
  • Mark and our Board are the ideal leadership team. I’ll save the “why” of this for another post about startup leadership, but it’s a big part of why I’m here and putting my all into it, every day.
  • I can walk to work!

So, I’ve been on the job 2 weeks, enjoying every minute of learning the technology and development process VP of Engineering Cory has built to date, and getting to know the stellar team of engineers, product and business folks. It’s also been enough time to validate all of the drivers for me deciding this was the place for me, and that is truly a great feeling. As I have shared with the oi team, this is the “calm before the storm…” We are in the war room strategizing how to reveal some new technologies and business lines that have been brewing in HQ at 20 Jay Street, DUMBO. Stay tuned and get ready, I think we’re gonna turn this thing on it’s head!

ASSERT: Learn by Testing

My 6-year-old daughter received a microscope kit as a gift. It’s not the 50’s-style die-cast behemoth I had as a kid, with all it’s frustrating sample mounting and focus issues. No, this is 2009, and this perfect kids’ ‘scope requires no focusing and is small enough for her to wear as a necklace. And, it’s pink which makes the necklace prospect all the more attractive.

I’ve been teaching her a little bit about science and encouraging her questions. But really, I am passive, watching her formulate theories and test them. Our freezer is full of “samples” from the last Brooklyn snowfall.

She is learning to learn by testing, to come up with an assertion she believes to be correct, and then by observation rule it in or out. The application to programming and building systems is obvious, but easy to forget. I’ve sometimes fallen into the trap of assuming something is true, and relying on that assumption without a proper assertion and test. With the overwhelming amount of reading material available on what works and what doesn’t from “cloud computing” to scaling Ruby, from development environments to search algorithms, it’s easy to fall back on assumptions, most often and dangerously someone else’s assumptions. Watching my daughter’s inner scientist emerge has been a good reminder for me.

I now assert, and have proven, that even New York City snow is made of ice crystals and melts at room temperature.

What’s a Good API?

API, or Application Programming Interface, is a term that has nearly become synonymous with Web API’s of late. Simply put, an API of this sort offers interaction with a server system over HTTP, delivering data as XML or JSON. I was recently asked in a job interview “What makes a good API?” I answered reasonably, but it got me thinking. Here’s a brief but more thoughtful answer, informed by recent real experience with Facebook, Flickr, Amazon and Twitter.

A good API has to value consistency as near religion. An ideal API experience for a new client of that API should require no documentation reading at all, assuming the client author knows what data she’s trying to pull from the provider. REST has gone a long way towards standardizing how this can, and perhalps should, be done. Twitter, for the moment, suffers a painful inconsistency between it’s standard REST API and the very useful search API. Granted, search is provided through the recent acquisition of Summize and the cobined Twitter and former Summize teams fully intend to address the inconsistency.

Orthogonality is another cornerstone. There should be very little magic done behind an API call, in that if I ask for something, I should get back just that something (or a clean list of somethings), in a more-or-less canonical form. Magic is tempting to add for convenience to clients, but it leads to overlap, and hence non-orthagonality. For maximum use and reuse, and interface might even require multiple calls, where one magic one would have sufficed, in order to retrieve the data a client needs. In essence, I mean that no side effects, good or bad, can result from a call for some data. I love the term “Principle of Least Astonishment” to embody thought that no one should be surprised by anything your API does. Although the API may ultimately become large, orthogonality as a principle of design will keep it relatively compact and obvious to client developers. They don’t have much interest in reading documentation, most likely, but a few well-written practical examples demonstrating this idea will be good enough for nearly all needs.

Smart version handling and clear policies must be in place at the inception of a good API. It’s got to have a supportable version policy (that is, how many versions will be supported and for how long?), and a simple version exchange protocal so that clients can report the version the support and expect, and servers can respond with their version and level of support for a particular client call. Further, friendly deprecation of API methods is a way to soft-fail calls that are going to be removed or re-purposed in the next version.

Things ought to be named intuitively. When the team at Digital Railroad took on API design, we made sure to eat our own dog food and be the first users of whatever resulted. Naming proved to be an unexpected challenge. I found that if we couldn’t name it easily, something about the design was likely amiss. Flickr and Amazon in particular have done a nice job of simple, consistent naming in their REST API’s.

Errors should be informative and specific, but use standard HTTP error codes. I worked with a technology provider in the photo world, who shall remain nameless here, that built a reasonably large API. It violated nearly all of the points I put forth here, but the most aggregious was in the area of error reporting. Imagine working with a method that takes no less than 20 parameters, then returns a “-1” upon failure in the body of an HTTP 200 response, with no additional diagnostic info! This is extreme, but really happened until we ultimately shelved the project due in large part to this kind of API nonsense.

There are more real-world principles of good API design, so shoot me yours.