I'm joining ifttt

I’m incredibly excited to announce that I will be joining ifttt starting in June. As you probably know by now, I love APIs and all of the possibilities that they open up. ifttt exemplifies the value of APIs more than any other company that I’ve seen. When I recently started looking for a job, they were on my short list of companies that I wanted to pursue. Things worked out and I’m honored to be joining such a talented team and helping continue to make ifttt great.

If you’re unfamiliar with the service, ifttt allows you to easily connect the services you use in useful ways. For instance, you could automatically save all your Instagram photos to Dropbox. Or save your Twitter favorites to Instapaper. That’s just barely scratching the surface of what’s available, and the company has big plans for the future. You can sign up for free to try it out for yourself.

For those of you who helped me out with introductions and meetings over the past six weeks (you know who you are), thank you for your kindness. It means a lot to me and I hope I can repay the favor in the future.

"It was a clue."

c|net interview with “Microsoft corporate vice president of search program management” Derrick Connell (oh, to have an eight word title) on Microsoft’s collaboration with Facebook on the new Bing social features:

"Zuck said, ‘Don’t try to do social by building social on the side. Build it into the experience,’" Microsoft corporate vice president of search program management Derrick Connell recalled.

"He said it four or five times," Connell said. "It was a clue."

Five times isn’t a clue, it’s a directive. So what did they end up with? (emphasis mine)

The seeds planted by that clue come to life today as Microsoft rolls out a new version of its Bing search engine. (snip) But the big change is a new gray sidebar on the right side of the page featuring a separate set of search results culled from the searcher’s specific Facebook friends.

Clue missed. Though, as someone who’s not a fan of Google’s Search Plus Your World maybe that’s a good thing.

Crockford: The Good Parts

Smashing Magazine has an interview with Douglas Crockford that’s full of great points. My favorites are below.

I’m much more impressed with people that are always learning. The brilliant programmers I’ve been around are always learning.

You see so many people get into one language and spend their entire career in that language, and as a result aren’t that great as programmers.

To learn new languages takes nights and weekends outside of work, and that’s a commitment. The great programmers are the people that are constantly picking a project and diving into it, learning a language that way.

On programmer empathy:

The best experience I had with empathy was working in marketing support. There were times I would go out into the field and hold hands with the customers and see the consequences firsthand of some of the crap we were delivering to them.

I think every programmer should work in customer support for the product they’re delivering.

On JSON becoming popular:

You know, the adoption of JSON sort of restored my faith in humanity because it was a good idea that won out, only because it was a good idea.

There’s a lot more gold in there too. Worth a read.

Source: http://coding.smashingmagazine.com/2012/04...

Hiring Is Dead

Jason Freedman:

Here at 42Floors, we believe hiring is dead. You simply can’t go hire guys like Dan anymore. And if you allow me to generalize for a moment, you can’t hire anyone capable of running their own startup. They don’t submit resumes. They don’t fill out job applications. They don’t call up recruiters.

The talent shortage for engineers is very real and a big part of that is the low barrier to starting your own thing. Joining a startup can be a great way to polish your skills before doing your own thing (especially if you’re very young) and more companies would benefit from embracing this shift the way 42Floors has.

Source: http://42floors.com/blog/posts/consider-th...

SwaggerSocket: 'REST' over WebSockets

SwaggerSocket: A REST over WebSocket Protocol:

The challenge, though, is that WebSockets are simply a protocol for communication–they do not define the structure itself. All the goodness that came with REST (structure, human readability, self-description) is abandoned for the sake of efficiency. This is why Wordnik created SwaggerSocket!

I don’t know if REST is the right term here (the quick start is more RPC than REST) but I definitely think there’s a future for APIs to use something like WebSockets to handle asynchronous bidirectional communication. WebHooks are not well-suited for super high-volume scenarios and that could be a place WebSockets shines.

Source: http://blog.wordnik.com/introducing-swagge...

The API Developer Experience Baseline

You’ve invested in building an API and now you want developers to use it. Very few companies can get away with creating a successful API ecosystem on technical merit alone. You’ll need documentation, SDKs, sample apps, debugging tools and everything else that goes into a great “developer experience”.

Based on my experience of working with an array of different APIs, here is what I believe to be the baseline level of support structure anyone who is serious about their API program should implement. This is geared toward web service APIs, but the principles can be applied toward any set of developer tools.

This is A LOT of work and not every company will have the resources to do this. Strive to support as much of it as you can. I’m a proponent of owning the entire experience, but if that’s not feasible for your situation one of the many API infrastructure companies out there can help you achieve much of this.

If you’re in the midst of making plans to open up a new API, make sure to consider the cost of building related tooling so that it’s not neglected until just before release, or worse, after the API has been made public. Developer’s first impressions are so important.

Within each section the items are ordered by importance.

Contents

Documentation

API Reference

A method-by-method, endpoint-by-endpoint, property-by-property breakdown of every possible request and response to and from the API. For requests, all parameters should be listed and described with a clear designation for required parameters. For responses, a sample representation should be shown in each of the supported data formats along with a list of properties and their descriptions.

In addition to the detail for each endpoint, an overview should be provided that describes how requests are to be made, the response formats supported, how authentication works, and anything else required to understand the conversation happening between the developer’s app and your API.

If you use a complicated authentication scheme like OAuth, a through description of the user authorization process with descriptions of each request and response should be included.

Lastly, a list of all possible errors should be provided. The first thing a developer will do when they get an error is Google it so make sure they get a hit.

User Guide

A higher-level guide to using the API. This should be organized by task. If a task requires multiple API calls, an step-by-step walk-through for each task should be described. If a SDK is the primary interaction point with the API the examples in the User Guide should be demonstrated using each of the supported languages/frameworks, though it is helpful to show raw HTTP requests/responses or cURL examples as well.

If every API endpoint is a logical single unit-of-work, the User Guide could be combined with the API Reference.

Getting Started Tutorial

A simple example that is short enough to be easily copy and pasted into the dev’s editor and run with only minor modifications (like setting a variable to their API key). This is to prove that the API works in the shortest amount of time possible. Keep it simple, simple, simple. Provide a version for each of the supported SDKs.

SDK-specific Documentation

Include instructions for obtaining the SDK and any installation or configuration steps required to use it. Provide examples for making a sample request and demonstrate the best way to handle errant requests for that language or framework. Any other information only relevant a specific SDK (for instance, a class reference or auto-generated documentation) should also be included.

Sample Applications

Sample apps should be standalone applications that demonstrate common use cases that help deepen understanding of what the API provides or gives devs a starting point from which to build their app. They should be functional with only minimal configuration and easily run or deployed. If your API requires OAuth, provide a sample app demonstrating how to authorize users. If another sample app requires authentication to work, include the auth example in the same package. Provide sample apps in all of your SDK flavors, ideally with all the samples being available in all languages.

Sample apps should be written using the idioms of each language and framework they are written for. They should instantly feel familiar for a developer experienced with that language. This will prevent the focus from shifting to the quality of the code contained in the example and away from the task at hand.

Debugging and Information

Error Logs

If an error is generated in a request from a properly authenticated user log and make it available to view later. Indefinite history is not required, but the more the better. This is particularly useful if an app is making requests of other users and the log includes errors for federated requests as well (minus any sensitive customer data). The more visibility you give into errors the less support you’ll need to provide for mystery circumstances and the more data your support team will have when they do need to help a developer consuming the API.

Usage Logs and Limits

If your API charges for or restricts the amount of usage, provide a complete history of all requests that incur a ‘cost’. All information that was made available to the API client in the API response should be available in the logs.

For usage that is metered, provide an as-close-to-realtime-as-possible indication of the current amount of usage and the available amount remaining in the current time period.

OAuth Utilities

For APIs that use OAuth (and I haven’t met one yet that wouldn’t benefit from it), make it easy for the developer to get started more quickly by pre-populating access tokens that authorize their user account to access their own app. For a great example of this check out Twitter’s developer center.

API Console

Provide a tool to make requests to the API and see responses. These should be real API requests, just from a web-based interface. Apigee provides a free console you can embed.

Test API

For APIs with requests that have side effects, provide a mechanism to simulate a real request/response interaction with semantics as close to the real thing as possible. Be careful with code-based ‘test mode’ flags, those tend to get left on in production. Make it easy to distinguish between real and test requests without requiring too much ceremony to make test requests.

Provide the same level of tooling for all relevant tools in this list (logs, etc).

Billing History

For recurring or usage-based billing, provide a complete history of the payments made to the account. For APIs that don’t involve a lot of requests, make it easy to see which requests were associated with which charge. For APIs with a lot of requests, provide a usage breakdown by type for each payment. Give developers as much information as possible so they can adjust their usage to meet budget restrictions.

Reset Key

Someone will post their API key on GitHub, I guarantee it (I have many times). Don’t make the developer wait for support to have a new key generated. Make available a self-serve API key reset function. Make it scary, provide a lot of warning and confirmation. Just let them fix it themselves.

Multiple Credentials Management

Allowing API consumers to create and revoke multiple sets of credentials on demand is useful for a lot of cases, but one in particular worth mentioning: demos. When demoing how an app was built (which happens a lot with APIs) make it easy for your developers to create temporary credentials they can disable when the video is over without the pain of having to create and configure a separate account.

SDKs and Libraries

Common Language/Framework Support

Provide officially-supported SDKs for the most popular server-side languages and frameworks:

  • Java
  • JavaScript/Node.js
  • .NET
  • Python
  • PHP
  • Ruby

If it makes sense to request your API from a mobile device directly, provide iOS and Android SDKs. Mobile SDKs should also include authentication helpers/controls and common UI elements.

The list of frameworks and languages you should support is not static or globally applicable. Don’t ignore a big potential audience because you’re not familiar with it yourself.

SDKs should be in sync with the latest version of the API with updates being released in tandem with new API releases.

Proper Distribution

Each SDK should be distributed in the proper package manager for each langauge (npm, Maven, NuGet, pip, Pear, RubyGems).

The code for SDKs should be open source under a OSI-approved and popular license. Make it available on a public code hosting site, preferably GitHub. Accept community contributions and fix bugs quickly.

Idiomatic

Co-opting and paraphrasing the dictionary defintion: using, containing, or denoting expressions that are natural to a native developer. Appropriate to the style associated with a particular group.

Community Code

Provide a list of community-provided libraries, extensions and components for all languages and frameworks, even the officially supported ones.

Communication Channels

This section is more human than machine and usually involves a set of professions dedicated to it, so I’ll just hit on the key points.

API Status Dashboard

Set up a site outside of your API infrastructure to provide availability updates. If there is an outage, report it there first. Have it push to a RSS or Twitter feed. Provide email updates for individual incidents. Keep it updated regularly throughout an issue. If it’s not a consistently reliable source of information for up-to-date status you can expect repeated “are you down?” support emails.

Blog

Provide a blog for announcing new releases, demonstrating how to use features and explaining commonly-occuring issues and questions. A blog is also a good place to do a test run for new documentation or samples to gauge feedback.

Twitter

Communicate new blog posts, releases and availability issues via Twitter account (or multiple accounts if it makes sense). Be very attentive and quickly respond to developer questions. Treat it like a conversation, not a broadcast mechanism.

Changelog

Provide a list of recent changes to your API, SDKs or documentation. Heroku has a good example.

Forums

Provide a way for your users to talk to and help each other. This can cut down on your support load and also keep developers engaged. If you outsource this to a site like Stack Overflow, watch it VERY closely.

Email Support

If your API is free, this may be low priority for you. If it is paid, move this to the top of this section. Some problems can only be solved by looking at private code.

Future Must Haves

Here are a couple things that I think will be standard issue very soon:

  • Real-time (meaning no page refresh) logs and dashboard updates
  • In-place example code editing and running from within documentation
  • One-click sample app deployments to platform-as-a-service providers (like the Facebook/Heroku integration).

I’m sure I’ve missed something. What is a must have for you when working with an API?

Looking to hire more staff to build all of this for your API? Post a listing on API Jobs.

Developers Build for the Platforms They Use

Dare Obasanjo:

A key principle behind the approach we’ve taken with the SkyDrive developer platform is that while it should be seamlessly accessible from Windows devices and apps, it should also be ready to enable developers on any platform to build apps that make SkyDrive more useful. It’s your data. It should not be limited to apps for a single browser or brand of devices.

The SkyDrive API looks clean and complete and Microsoft is taking the right approach to it by encouraging developers to build for any platform. When you’re playing from behind (in this case, in consumer adoption), you can make up ground by opening things up to developers more than your competitors.

There’s one big problem I see though. As I tweeted yesterday:

GDrive, SkyDrive, Dropbox. I’m betting on the one with the API and that the majority of devs use. Platforms win.

SkyDrive and Google Drive have APIs/SDKs and will get a lot of users from existing user bases of related products. But the operative word in that tweet was ‘and’. From my observations, near 100% of the developers I know use Dropbox. Some will use Google Drive (especially if they work at a place using Google Apps) and relatively no one uses SkyDrive (cue some MS employees and MVPs I know chiming in with how great it is).

Developers build for the platforms they use. That’s why I think Dropbox will ‘win’ the cloud storage platform wars. What it means to ‘win’ remains to be seen.

Source: http://windowsteamblog.com/windows_live/b/...

Limited Launch for Google Drive SDK

Ars Technica:

The new Google Drive APIs provide programmatic access to the contents of a user’s storage account, but with a number of significant restrictions that limit the scope of how developers can presently use the service. The APIs are only available to Web applications, which the user must “install” into their Google Drive account through the Chrome Web Store.

Web applications that use the APIs can only access files that they created themselves or files that the user individually chose to open in the application. The latter has to be done through the Web-based Google Drive interface or an embeddable Web-based file picker supplied by Google Drive. This model isn’t conducive to supporting native third-party mobile integration and rules out many common usage scenarios that are supported by competing storage services.

Maybe this is because they rushed it out the door as some people speculated, but it’s not a bad strategy to roll out a new API or SDK in a limited fashion focusing on the most compelling use case you want to drive usage of first. You can always add more features and use cases later. Harder to take away bad ones once they’re out.

I tried getting the ASP.NET MVC example up and running today but sadly it was incomplete (handling the OAuth2 callback wasn’t built in) so I didn’t get through it unfortunately. The idea that any web app can register as an editor for a file type differentiates Google Drive from the current competition. It will be interesting to see what kind of traction it gets.

The fight for the file system of the internet is definitely heating up. Dropbox has better clients and a much simpler API (that you can use for more things) but Google pushed the needle forward today in a big way.

Source: http://arstechnica.com/business/news/2012/...

Could Light Table get in trouble with Microsoft?

An experimental project from the Visual Studio team called Code Canvas resurfaced today in a blog post by Kael Rowan. Code Canvas has been around since 2007 and “explore[s] design alternatives when dealing with source code on an infinitely scalable two-dimensional surface.” Here’s a video to give you a better sense of it:

More recently, Microsoft has actually shipped an add-on to Visual Studio called Debugger Canvas which appears to be based off of the work done in Code Canvas combined with Code Bubbles, an Eclipse plug-in that uses similar concepts. More videos for your enjoyment:

Code Bubbles:

Debugger Canvas videos.

Microsoft is clearly invested in this concept.

What does this have to do with Light Table? I found this part of the announcement post interesting:

Towards the end of my time on the Visual Studio team, I came to the conclusion that windows aren’t a good abstraction for what we do.

And

While I worked on Visual Studio, I began to see the pieces of what we could do here.

Chris cites Bret Victor’s incredible ‘Inventing on Principle' talk (which you must watch if you haven't) but fails to cite the work done at Microsoft, related to the team he was on, as inspiration. It seems like a glaring omission.

Maybe I’m seeing smoke where there’s no fire; Microsoft is a big company after all and I’ve seen cases where even members of the same team don’t know what each other are working on, let alone what R&D is doing. But I, as a backer of the Kickstarter project, hope that these similarities don’t result in future legal problems for Light Table.

$1B was a bargain

Sara Lacy:

I think $1 billion is the right price, oddly enough. This always puts people in fits, but the reality is that when it comes to a fast growing company, the math isn’t about revenues or even near term revenue potential. It’s about how badly the acquiring company needs or wants it.

This was a cash and stock deal, and poised before a $100 billion IPO, Facebook’s stock is essentially monopoly money at this point. $1 billion is a rounding error, but it’s a rounding error that allows Facebook to do three things: Re-boot photos, a process which has always been the core of the social network’s glue; take out a potential competitor, since Instagram was increasingly viewing itself as another social network; and most importantly, keep Instagram out of the hands of Google or Twitter. For $1 billion of Facebook’s stock currency, all of that was a bargain.

Well put. What a lot of people seem to miss is that value does not always mean revenue or profit.

Source: http://pandodaily.com/2012/04/09/kevin-sys...

Building API Jobs, Part 1: Python and Flask

While building API Jobs I used a lot of things I’ve never used before so I thought I’d do some mini reviews of each of the pieces that went into building the site. I started this as one post but it’s getting really long so I’m going to chop it up.

Part 1: Python and Flask

I had built a couple of toy projects using Python to learn my way around a little bit but this was the first real web site I built with it. Django looked like overkill so I went with Flask because it’s much simpler. It’s essentially a Sinatra for Python.

Python is a great language. It’s terse but expressive. The ecosystem is robust and there’s a package out there for just about everything important. pip is a capable package manager, though managing environments with virtualenv is sort of a pain because of manual activation and deactivation. autoenv may help, but it’s still pretty new.

The simple cases in Flask work almost too easily. Define a method, add a route decorator, save the file and run python web.py from the command line and you’re up and running. For the most part this site is contained entirely within one web.py, though it’s starting to feel unwieldy. I think I’ll be looking into Blueprints soon. Locally I just use the built-in web server, but when deployed to Heroku it runs on gunicorn at the recommendation of a former coworker who knows things.

I used the default templating language that comes with Flask called Jinja2. It’s a capable templating language. One of my favorite parts is its support for custom filters which are sort of like C# extension methods you can apply to any output block e.g. {{ job.description|striptags }}. You define them as simple functions and then register them with the Jinja engine.

Some of the pages require sensitive information being transferred so I wanted to easily mark a method as requiring SSL. I was surprised to see this wasn’t built in so I wrote a custom decorator. It worked great locally but when deployed to Heroku it resulted in an endless redirect. Heroku runs your app behind a proxy and if SSL is configured, that’s handled at the proxy level and not the app level so if you inspect the requested URL it’s never using HTTPS. Heroku passes a x-forwarded-proto header though that includes the original URL. My custom @https_required code is here.

I played with a few different config setups before settling on a file named config.py that contains some variable assignments. Then I can get access to them like this:

import config
config.TWITTER_CONSUMER_KEY

The config.py does a check for an environment variable called ‘REALM’ and if it matches ‘prod’ resets the variable values to the production versions. Like so. I don’t know if this is the best way to do it, but it works and it’s simple.

The only web logic that lives outside of web.py is the handling for the AJAX actions of the admin interface. I first defined a class that maps the HTTP method and the resource to a method call to handle that action. The actions return a tuple of a dictionary and a status code. Then in the web.py file, I wire up a route to pass through the requests to the command processor and turn the response into JSON. I’m guessing there’s probably an easier way to do all this, but I’m still learning.

One other janky thing I had to do was how to handle redirects from the non-www domain to the www version (Heroku recommends you don’t use the apex domain as the primary one). I wanted to keep the requested paths in tact when redirecting. I couldn’t find the place to hook into Flask to intercept it before it hit any methods. I think signals is what I wanted but my quick attempts to get one to work didn’t pan out. Instead I created a second Heroku app with a catchall route that does the redirection.

Coming up in future posts, my thoughts on Heroku, SendGrid, Searchify, Stripe, Twitter Bootstrap, Redis and more.

Any questions? I’d love to know what you’d like to hear more about.

Leaving Twilio

After two intense years, I’m leaving Twilio in early April to find a new challenge to take on. It’s been a great ride here and I’m very fortunate to have been able to work with such an amazing group of people that have taught me so much. I can see my fingerprints all over the company and I’m pleased with the legacy I’ll leave behind. Being a part of a company that grew in both headcount and customer base 10x has taught me more than any other professional experience I’ve had. It has simultaneous felt like I’ve worked here two weeks because of how fast it went and ten years because of how much we accomplished.

Ultimately the company and I grew apart a bit and I didn’t feel like it was the best fit for me any more. It’s time to move on to something new but I’m yet not sure what that is. I’m interested in pursuing product or leadership roles around APIs and developer experience programs. If you are hiring for something in that area or know someone who is, let’s chat.

La Baraka: No way I am calling you for a price

labaraka:

We’ve outgrowing the manual payroll process we’ve been using so far so
I was looking for a managed payroll solution.

I already knew about ADP and Ceridian but decided to quickly check
with Uncle Google to see if there are other options in Canada. Turns
out that, yes, there are other providers.

Self-service is increasingly important for service providers. I was just thinking about this exact thing this morning when I registered selfserveapis.com.

Sparrow for iPhone (App Store)

It took me exactly 10 seconds to love Sparrow for iPhone’s user interface. When I saw screenshots earlier today I thought it looked so much like Loren Brichter’s (of Tweetie fame) work that I thought that might be what he’s up to these days. Turns out it’s just heavily inspired by his work.

$2.99 is worth it just for pull to refresh.

Go2Shell (Mac App Store)

This little gem adds a button to Finder to open the current window in your terminal of choice (Terminal, iTerm, iTerm2, etc). Saw this on Hacker News today and turns out I already had it installed but hadn’t dragged the app to the Finder toolbar to add the button. Also accessing the configuration options is a little obscure. Run open -a Go2Shell --args config from any command line after installing.