John Sheehan

Launched

Today we opened the doors on Runscope, our new set of tools for debugging, testing and inspecting your API integrations. In addition to that, we announced that we’ve received a seed round investment of $1.1M from True Ventures, Lerer Ventures, David Cohen, Andreessen Horowitz, Nat Friedman, Jon Dahl and Ullas Naik.

While launching to the public is a lot of fun and the culmination of a lot of hard work, it’s just the starting line for the next stage of what we’re trying to accomplish. Even so, getting here required a lot of help and support from a great many people and I’d like to thank those that were instrumental in helping us get this far.

First off, my wife Emily. When I told her I wanted to quit my job to start a company she didn’t even flinch. When fundraising hit rough patches she was unwaveringly supportive. Thank you honey.

Next up, my co-founder Frank and the rest of the team that has joined us in the past few months: you’ve done amazing work in a short period of time and you’re a blast to work with. Honored to be working with you.

To Nat Friedman, Jon Dahl, Ullas Naik, Adam D’Augelli and the True crew, David Cohen, Ari Newman, Max Stoller, Steve Schlafman, Chris Dixon, and Frank Chen: I couldn’t ask for a better set of investors. Thank you all for your support.

And lastly to everyone else who helped with intros, reference calls, testing out the preview, advice, lawyering, finding office space, candidate referrals, etc: thanks for playing a small part in helping us get this far.

Now, the hard part.

Designing APIs for Humans

Earlier this month I gave a talk at Devs Love Bacon on an API design philosophy I picked up while working at IFTTT I’ve been calling ‘APIs for Humans’. Sadly, it’s not about this:

OH at @devslovebacon “I thought the “APIs for humans” talk was about controlling humans” #devslovebacon

— Julian Cheal (@juliancheal) April 12, 2013

At IFTTT I identified three major areas for how non-developers end up consuming API data in significant numbers. In this talk I cover what those areas are and how you can tailor your API designs to encourage developers to build human-friendly integrations.

Since I had extra time I threw in a few points on developer experience too. After all, developers are humans too.

The Good and the Bad of OAuth 2.0 Authorization Implementations

While testing out a new tool I’m working on that uses a variety of OAuth2 providers and thought I’d catalog some of the quirks I came across. This is just for the authorization flow, not for actually making requests once you’ve secured a token.

Now that the OAuth2 spec is solidified we should start seeing less and less of these issues.

Google

Good: The APIs Console is one of the best out there. My favorite feature: allowing you to specify multiple callback URLs for a single app. This makes testing different environments way easier because you don’t need to go back and constantly edit the callback URL value.

Good: The OAuth 2.0 Playground is fantastic. It will show you all the HTTP requests that are made for a standard auth flow. This makes it really easy to debug issues on your end by comparing the requests. I used it to diagnose the following problem.

Bad: When requesting an Access Token the request will fail if you include any parameters that it is not expecting. Google does not require a state or type parameter when getting the token like some other APIs do and will give you a 400 Bad Request with an invalid_request error if they are included.

Bad: The scopes options are not immediately obvious. There’s a huge list of services and you must enable them individually (good) in the ‘Services’ section of your project in the APIs Console. This page though does not list the scopes value to use. The Playground does have what appears to be a complete list.

Facebook

Bad: If you just want to use OAuth with the Graph API, you still need to enable “Website with Facebook Login” in order to set the Site URL. This is hidden by default and took me a little bit to find it. This setting restricts which domains they will redirect back to.

Good: The Site URL only requires a domain instead of a full URL which means you can change your callback URL path without breaking your app.

37signals

Bad: When you create the app you select which services you want your app to have access to but during the auth flow only one of the services is displayed.

Bad: There’s no support for limiting access to read-only via scopes. The only option is full read/write for all of the apps selected.

Stripe

Bad: Stripe does not use a client_secret. Most client libraries and OAuth examples use it so it may be confusing for experienced developers wondering where that value is.

Bad: This is not technically wrong, but it isn’t common. When exchanging the code for an access token you are required to send an Authorization header with a value of Bearer and your Stripe account secret key (either test or live). I’d rather they just tell you to use the secret key as the client_secret and not require the additional header.

Instagram

Bad: The docs say that the scope parameter is optional but will give you an error (400 OAuthException - Invalid scope field(s)) if it isn’t specified. You should specify at least ‘basic’.

Box

Bad: The redirect URL settings requires HTTPS which can be difficult if you’re trying to test locally (for instance my test app runs on http://localhost:5001 which is accepted every where else). Box has informed me this will be resolved soon.

Bad: Does not use scopes for read-only or read/write access (is configured with the application). Box has also told me they will be changing this once they have more than one scope.

Microsoft Live Connect

Good: Permissions are set via an extensive and clear list of scopes. Very nice.

Stack Exchange

Good: Callback URL validation is set via domain only (similar to Facebook).

GitHub

Bad: Scopes must be specified comma-separated, contrary to the OAuth2 spec. This is on the roadmap to be fixed.

App.net

Good: The application manager allows you to generate a token for yourself with custom scopes without having to go through the flow. This is extremely helpful during development.

Others

Here are some others that I tried that I didn’t have any notable issues with: MailChimp, Foursquare, Wordpress.

Here are the services I desperately wish would move from OAuth 1.0a to OAuth 2.0: Twitter, Dropbox, LinkedIn

If you’ve come across a unique implementation quirk of your own, post it below in the comments.

Related Posts

• The API Developer Experience Baseline
• Don’t Build the Best REST API, Build the Best HTTP API

Age

This post is a little more personal and not at all technical. I realized I’ve been wanting to write about this for awhile.

On the latest episode of Hanselminutes two of my favorite internet friends had a discussion on age as they are nearing their 40th and 45th birthdays. I happened to come up a couple times as a reference point for The Young’uns.

Age has always been a sensitive issue for me. When I was 5 my mom homeschooled me and when she couldn’t do it anymore and it was time to go to public school I was effectively done with first grade so she bumped me ahead to second grade. The rest of my primary and secondary school years I trailed all my classmates in age by a year. I got my license my junior year, graduated at 17, etc. I played sports on teams consisting of all older players. I was always very determined to prove that my age didn’t matter.

When I started running companies when I was 15 my age was an advantage. It got me attention and customers. When I started working real jobs at 19 it was also an advantage because people couldn’t believe how mature and experienced I was “for his age.” At about 25 when all my peers had experience too (with degrees to boot) it wasn’t as advantageous.

Now I’m 31. In the SF tech scene I frequently feel old. My experience frequently gets deferred to (which often makes me slightly uncomfortable). Some of the younger engineers I’ve worked with lately have made me feel really old. They’re insanely smart but make me realize how much experience I actually have now (going on 16 years of doing computer stuff for money). 30 under 30 lists drive me crazy not because that’s my goal in life, but just because it’s impossible nonetheless. My wife consoles me by saying there’s plenty of time for 81 under 81.

Back to the Hanselminutes episode. Rob talks about a recent dinner we had together where he was giving me some advice (that I appreciated) and my reaction. I (not surprisingly) reacted by giving him a look that said I have it all under control. Almost certainly I was overcompensating for my age insecurities. I rarely feel like I do have everything under control and I crave insight from people more experienced than me.

At the same time, I do know some things now. More importantly I know what I don’t know. All of that experience has lead me to a position where I can be a founder of a startup. I’m not doing this because I’m young and impetuous and want to ride the wave of the current ‘bubble.’ I’m doing this because I know what it will take for me to be happy in my work and I’m not going to spend any more time not pursuing it. I’ve known that for a long time, but I’m at a point where my age is an asset in making this happen. So I’m going to.

Runscope

I’m very excited to announce that I have co-founded a company. If you use APIs in your mobile or web applications request an invite to our early preview. We’re still very early in this and will be talking about more details as we progress.

The plan when I moved out to San Francisco was always to eventually start something of my own. I learned a ton working at Twilio and IFTTT and now hope to apply that knowledge to build a great company. Now’s the time. We’ve got a great team and a giant problem to solve and I can’t wait to show it to all of you.

Follow Runscope on Twitter to track our progress.

Box API v2: Less is More

Box has updated their API to version 2 and has simplified it along the way. The highlights:

• Consistent request/response models
• Convention-based attribute names (please do this in your APIs)
• No more XML, huzzah!
• Better events streams (I hope that Webhooks follows)
• Settled on OAuth2 standard

My favorite line:

There’s an inherent impedance mismatch between XML and regular humans.

These are all very developer-friendly changes. If you’re designing an API, there’s a lot to learn from Box’s experience.