OAuth is awesome, OAuth is horrible.

Photo: Micro Ecosystem by Pierre Pocs

Introduction

After writing the Runscope API, and several OAuth API clients to other services. I’ve finally had some time to figure out how I feel about OAuth 2.0… OAuth is awesome, OAuth is horrible.

My co-founder John has already written a lot on OAuth Implementations. So, I won’t cover those specific APIs and how they use OAuth. Instead I’d like to talk at a high level about the experience interacting with both sides of the OAuth equation.

OAuth is awesome

The concept of delegating access of your data without sharing credentials is AWESOME. OAuth is prerequisite for ecosystem building. If you don’t want a community of applications and developers that work together, you don’t need an OAuth API. OAuth Applications are by and large, web applications. Web applications are probably the easiest to build, distribute, and discover.

An application you build for yourself can be easily used by others without having to share code or modify authentication configuration. This fundamentally changes the user experience from the old-world model of “download this tarball and modify the user/auth token or give me your login info” to a much more frictionless “click here for new functionality!” This creates a strong network effect; as the number of easily shared applications grows, the more everyone can benefit from the new functionality without additional work.

Building a community around your API also magnifies the reach of niche features. If you’re building a strong ecosystem of developers, highlighting and encouraging community contributions is essential. There are always more feature ideas than you can possibly implement by yourself.

OAuth is also great as a user when you can properly reason about scopes and permissions. Empowering the data owner to control access to their own information is crucial in building trust. There’s a reason you shouldn’t hand over your username and password for you Gmail account to everyone who wants it. The same goes for your API access. OAuth gives you the option to define levels of comfort and trust that are not binary.

Overall, the end-user experience of OAuth is great when done right. And it turns siloed and fragmented web services into a more connected and powerful network of applications.

OAuth is horrible

Server Side

Writing an OAuth powered API is still too much work. A minimal implementation is still many hundreds of lines of code. There’s so much boilerplate code, e.g. ‘required’ parameters that end up largely vestigial for most implementations. There are very few OAuth 2.0 provider libraries, and most libraries I’ve seen have very poor documentation and are usually barebones implementations. Which means if you want to support 'optional’ parameters or other types, you’re going to have to roll your own anyway.

OAuth requires a lot of server side state. Storing authorization codes, access tokens, application client_ids, scopes, are all necessary. This is another reason why adding OAuth to your API is more work than it seems initially. Do you create database tables for everything? Do you expire authorization codes or access tokens? Now you have to use redis/memcache to automatically expire data or build an entirely new system cleanup your database tables. These are the hidden costs of OAuth implementations. Unexpected details that crop up halfway through an implementation will cause an engineer to pull their hair out.

Client Side

Any OAuth provider’s documentation has to start from the foundations of OAuth. You can’t assume that all developers that show up at your API have heard of and/or built OAuth clients before. This means your documentation is now many pages longer than it would have been originally. There is no “1 line demo” that gets you up and running if you’re building an OAuth powered app.

Building simple apps takes a lot of work. There are many libraries that aim to help, but they are framework specific, and still require much thought on how to integrate.

To start, you’ve got to setup an application with the service provider. Usually this requires some information about your application, URLs for making callbacks to, website urls, names, etc. There’s a bit of upfront setup work before you can even test out an OAuth API.

Furthermore, OAuth Clients have to be Servers as well. The main OAuth flow is a web based flow. It requires you to setup a full fledged server and register routes that can be redirected to. This adds complexity to an application beyond “set the username and password in your http client”.

If you are running multiple environments, (i.e local dev/integration/production), you must duplicate the upfront setup of creating different applications with different redirect URLs. Not to mention the challenges of managing OAuth applications details in a team environment where multiple people need access to view and update them.

Sanding off the Rough Edges

We use OAuth for the Runscope API, but to make it easier on app developers we’ve added a few features to help reduce the friction on building new Apps.

Personal Access Tokens

When you create an application, we immediately authorize it against your own account. We show you on the Application page an access token (and setup our Request Editor) so that you can easily test making API calls right away without having to build any OAuth flow code.

Authorize URL Builder

When building a new app, setting up the proper redirects with all the correct parameters is non-trivial. We’ve added a URL builder that lets you select which scopes you want to request and automatically populates your client_id, callback_url, and other required parameters.

Multiple Callback URLs

One application can have more than one callback URL associated with it. We check for valid a redirect_uri against the list on the application, if any one matches then we proceed with the OAuth flow. This lets you set callback URLs for your local, test, and production environments on the same Application. No need to switch out client_ids or client secrets if you don’t want to.

OAuth Tool

For other OAuth2 APIs, we’ve built a token generator that can help in the development / debugging process.

Other Tools

There are also some other OAuth aggregator tools out there. Services like foauth and oauth.io help ease the pain of developer setup work, and their existence is further proof that OAuth isn’t easy to get right.

Conclusion

OAuth is awesome for consumers once you get passed the pain of developing against it. Every day the global API community grows by making it easier to try new concepts, build great applications, and share data and ideas with other individuals. Our mission at Runscope is to help all API developers navigate the world of HTTP and HTTP APIs, and our OAuth related tools take a step in that direction. Growing a healthy ecosystem of API providers and developers will help fuel the next round of innovation on the web.

Debugging the Stripe API using Runscope

Raging Code Monkey by Plognark

Runscope

Runscope is a service that lets you inspect and debug HTTP traffic. I started working on Runscope with my friend John to build the best developer tools I could. We build a lot of internal services at Runscope, and we also use a lot of great 3rd Party APIs.

One of the most frustrating parts we’ve found of building applications that use lots of APIs is just being able to see and understand the requests going back and forth. This blog post takes a look at one of the APIs that we use - the Stripe API - and how we put it through Runscope to help us debug and test our integration.

Setup

First, sign up for a free Runscope account

Next, find your bucket key. This key is different for every bucket, and it becomes part of the Runscope URL you’ll need later.

Update Your Code

To use runscope with the Stripe API Libraries, all you need to do is add one line of code !

Just change the API endpoint from

https://api.stripe.com

to

https://api-stripe-com-<bucket_key>.runscope.net

Once you do this, traffic from your application will begin showing up in your Runscope dashboard.

Here’s an example of how to change the API hostname in the stripe libraries.

Python

All you need to do for the python library is add a line to set the stripe.api_base:

import stripe

# not my actual api key! :)
stripe.api_key = "sk_test_mkGsLqEW6SLnZa487HYfJVLf"

# replace <<bucket_key>> with your own bucket key
stripe.api_base = 'https://api-stripe-com-<<bucket_key>>.runscope.net' 

# Example get charges (this will be 200 OK)
print stripe.Charge.all(count=3)

Ruby

Once again, all you need to do is set Stripe.api_base to the Runscope URL.

require "stripe"

# not my actual api key! :)
Stripe.api_key = "sk_test_mkGsLqEW6SLnZa487HYfJVLf"

# replace <<bucket_key>> with your own bucket key
Stripe.api_base = 'https://api-stripe-com-<<bucket_key>>.runscope.net'

# Example charge (this will be 200 OK)
Stripe::Charge.create(
  :amount => 400,
  :currency => "usd",
  :card => "tok_1RS9k7Gtc2PBmG", # obtained with Stripe.js
  :description => "Charge for test@example.com"
)

PHP

For PHP, just set Stripe::$apiBase to the Runscope URL

<?php
require_once('./lib/Stripe.php');
// not my actual api key! :)
Stripe::setApiKey("sk_test_mkGsLqEW6SLnZa487HYfJVLf");

// replace <<bucket_key>> with your own bucket key
Stripe::$apiBase = "https://api-stripe-com-<<bucket_key>>.runscope.net";

// Example plan update (this will be 404 Not Found)
$p = Stripe_Plan::retrieve("pl_QUE6BJcvg7LBmp");
$p->name = "New plan name";
$p->save();

Java

Unfortunately the java library declares the API_BASE as static final variable so it cannot be overwritten easily. There might be a way to dynamically rewrite the Stripe class or use reflection to make it non-final. If anyone has suggestions other than patching the official stripe lib to let you assign API_BASE, I’d happily update this post.

C#

The unofficial XamarinStripe library for C# also sets the base URL as static readonly, but we’ve submitted an issue to make it configurable. Stay Tuned!

Now what?

You can see each of our test requests in the Dashboard here.

You can expand any message and see the full HTTP Request and Response that was made.

You can take an existing request and edit & retry it in your browser. This is helpful when you’re trying to quickly figure out what parameters to change to make a request work correctly. It’s also a good way to make POST/PUT/DELETE requests from a browser.

If all else fails, you can create a Public Share link to send to the support team so they can see exactly what the request issues are.

Conclusion

Having Runscope log requests for us lets anyone on the team quickly see what went wrong on our end after the fact. It also gives us a good sanity check when releasing new versions of our code to make sure all the data we expect to see is there being sent.

Now that you see how easy it is, go try Runscope out for yourself.

If you’d like to see other posts about how to use Runscope with other API libraries, let me know!

New Beginnings

I recently quit my job to try something both fantastic and frightening.  I’m starting a company with my friend John.  It’s called Runscope.  We’re building tools to make it easier to work in an API driven world.

We’re still “Under Construction” ;) but we’ve got some good feedback so far.  There will be more news on Runscope later… this post is about something different. 

It’s a long road from idea to company to successful company.  There’s already so much that I have learned in the short few months I’ve been at it, and there will continue to things that I am surprised by.  Leaving a nice, structured, secure job to jump headfirst into an unknown is a big step.

The most striking thing to me so far is that everything takes time.  Startups, naturally, move fast, look for quick growth, and aren’t for those who can’t keep up.  But when every fiber you have is telling you to go faster, there are things that just take time.  Be prepared to spend time waiting on lawyers, waiting on leases, waiting on the next cup of coffee to brew – just to name a few.

You constantly want to be done with everything yesterday, but there’s always a tomorrow and something new to wait for on the horizon.  So my advice to myself is: Take a deep breath.  Keep getting stuff done, be patient, and don’t worry about the little things.