APIs We Love: DonorsChoose.org’s New API Console »

Today there are thousands of APIs doing amazing things - revolutionizing personal data, exposing powerful cloud services, and transforming the way businesses work. We particularly love APIs that make the world a better place - like the API for DonorsChoose.org, an online charity that makes it easy for anyone to help students and classroom projects in need. We're excited to announce that you can learn, explore and test the DonorsChoose.org API on our Providers Page (now with over 40 APIs!) or in the DonorsChoose.org developer guide. DonorsChoose.org uses Apigee To-Go to embed the API Console in their site. 

The DonorsChoose.org API lets developers help classrooms right from their websites or apps. It has been used by Chevron, SONIC Drive-In, NBC Universal, Starbucks and others to build customized cause marketing and community engagement. Now you can use the Apigee API Console to get started quickly, exploring project listings and integrating donation functionality right into your apps. 

Tell us your app plans, send feedback and let us know additional API Consoles you'd like to see - email us at .(JavaScript must be enabled to view this email address). 

OAuth: Flow for mobile apps »

In my previous post, I talked about how OAuth allows users to grant third-parties access to their web services without sharing their passwords.

In that previous example, our user (Bob) accessed his Twitter account through the bit.ly web site.

This time, let's look at what happens when Bob is using a mobile app instead of a web app.

It’s pretty much the same for a mobile app as a web app. When you fire up your mobile app and want to access Twitter, you don’t want to have to give the mobile app your Twitter password and store it on your phone.

In the same way as happens for the web app,  the phone app opens a browser window and directs Bob to login to Twitter (and authorize bit.ly to use his Twitter account) - using OAuth.

The phone app never sees Bob’s Twitter password.

The phone app uses its OAuth credentials to retrieve credentials for Bob. It stores these locally. In this way,

OAuth allows this one phone app access to the Twitter service on behalf of one user (Bob).

This all happens through your browser. There are both advantages and disadvantages to this:

- The advantage of this is that the app never sees your password.

You don’t have to trust the person that built the app or worry about losing your phone (as much).

If Bob loses his phone, he can log into Twitter and revoke the credentials that Twitter gave the phone app. (A thief cannot uncover the password, only the token.)

- The disadvantage is that the app has to open up a browser window. This possibly breaks the flow of a nicely designed UI for a mobile app.

There are ways in OAuth around this but you eliminate many of the security reasons for OAuth in doing so. Twitter and Facebook for example, have made the choice to have everybody log in through the browser.

Next time: Why OAuth is good for API providers.

Armrest & REST API Design »

Last week I flew from Doha, Qatar to Brussels, Belgium. The fella in the aisle seat fell asleep before takeoff. The road warrior code of chivalry indicates one should never wake a fellow traveler.

So I stayed in my window seat for 8 hours. After a few minutes it became obvious that my armrest (singular, my neighbor had usurped the other one) was uncomfortable.

Here's a picture of the armrest.



The armrest has many problems. The biggest: you can't rest your arm on it.

If you try to relax, your elbow gets sucked by gravity into the cutout and pinched unpleasantly by hard plastic. If you deal with the pain and fall asleep you will wake to find your ears exploding because you inadvertently cranked up the volume, the flight attendant will be tapping your shoulder asking why you paged him and your reading light will be shining in your dilated eyes.

The Airbus A330-200 in which I was traveling holds 250 people. That's 2,000 man hours of discomfort per flight injected into the universe because of bad design.

So, why does such an obviously bad, pain-inflicting design make it into the world?

Because it cost-effectively solves other, non-customer-related problems! In this case, it is a clever way to store the remote controller while still keeping it accessible to passengers. It’s also done in a way that doesn't require an expensive reworking of the interior: cut off part of the armrest, put a hole in it and reattach on a hinge. Done! In-air multimedia problem solved!

What does this have to do with REST APIs?

Even with the best of intentions, API teams often stop short of doing the right things for their customers. Customers of APIs are application developers. Application developers are smart, busy, and born to suffer (especially Objective-C developers, NSThatsADifferentTopic). But they are also often musicians, gamers and aesthetes. They are attracted to things like truth and beauty. And they are attracted to good, self-consistent API design.

So, why do API teams often stop short of delighting developers? Because the time and cost of learning to do the right things and getting them done often seems prohibitive! At Apigee, we share everything we learn on our blog, twitter @Apigee, YouTube, API Craft on Google Group, and in our webinars.

There's no reason to walk the road to creating a fantastic API alone. If you know of an API or an API team that's not doing things right or is trying to go it alone, please send them to us. We'll get them straightened out.