Skip to content

Designing Irresistible APIs

I spend a lot of time traveling around and teaching people how to make better APIs. The current focus of my talks is Designing Irresistible APIs – I’ll be giving this talk (or a version of it) at OSCON, and just presented it at Future Insights Live, as well as doing a webcast to get people excited about OSCON.

I’ve uploaded my slide deck on slideshare but I thought I should make a brief post summarizing the ideas in there. There’s a newer one here, and a copy of my API 101 slide deck from APIStrat Chicago.

API Design Process

  1. Understand the business value of your API.  Are you trying to drive usage, integrate with partners, attract new users, excite existing users?  Your API is unlikely to directly drive revenue unless it’s your main product, so understand what you want to get out of your API before you even start creating it.  Note that partner integration is a very strong business value, but what you want to know here is what would you tell your CEO if you were trapped in an elevator with him and he asked why you have an API.
  2. How are you going to measure success?  API usage?  How many people use the API vs. the website (APIs are not as resource intensive and can be automated, helping you to create more solid integrations)?  How many partners are integrated?  Again, this is critical for the design process, and critical for communication to your management team, partners, and developer customers.
  3. What use cases are you going to support?  Mobile, website, reporting… note that if you want to support a mobile experience, even for third party developers, you have to somehow support the idea of a single call per screen on the device – otherwise mobile developers will go elsewhere to integrate.
  4. Now you can design your API.  Using a schema modeling language like RAML, blueprint or swagger is a great way to visualize what your API looks like.  Extending the syntax to allow for expansion or defining exactly what a developer wants should be decided at this point.  Here’s a post that discusses the choices you can make, but remember that you’re not making these decisions in an absolute way or in a vacuum, you’re honestly trying to meet the needs of your users through the use cases you’ve identified.  Let go of your desire to have a fully RESTful API if it doesn’t serve the needs of your users.  Make the use cases dead simple – if you don’t make a usable API, nobody’s going to use it.  Yes, this applies even to internal APIs – if your API is difficult you’ll be swamped with support requests and faced with a lot of internal strife.  Honor your users and their time and they’ll repay you by loving your API and evangelizing for you.
  5. Great, you’ve designed your API and even made it.  Now check and make sure – are those use cases dead simple?  Great!  Now what you need to do is create a fantastic developer experience, from on boarding through all their use of the system.  Create a great developer portal.  Provide small-bite tutorials with example code.  Make the developer experience fun and engaging.  Play with your users!

Your API needs to be a first class product to succeed.  Give it the thoughtful consideration you do for any of your products and you’ll have a much better chance of having a successful, engaging API.  If you want to learn more about APIs, you can find many great articles on API Codex, curated to give you an array of high quality content from some of the smartest API experts out there.

Posted in Uncategorized.

API Playground

USACE, EUCOM deliver special needs playground to Croatian community

As a developer evangelist who frequently works with other developer evangelists, we sometimes find it hard to get people to understand what’s awesome about APIs. I’ve gotten pretty good at API 101 – teaching people what an API is and how it can create opportunities for a company, but now I’m ready to move on and create the upper division course – API 201. How to play. How to really put these things together and make them sing.

In this course, I will let attendees play with existing prototypes, show them how to create their own using IFTTT and other technologies, and help people understand that while a mobile application for Twitter is fun, having Twilio robo-call your mom when she sends you yet another Snopes legend is awesome. Rube Goldberg is my hero. I plan to create all sorts of fascinating things – based on your travel plans, what time do you need to leave for the airport? You should get a text telling you to head out. When you’re at a conference and forget a connector, maybe there should be an app for you to keep a checklist in for future conferences. Visiting a new location? Where can you find a gluten-free cupcake? Did you exercise and stick to your diet plan? Well then, you should get to actually eat the cupcake too!

These and other ideas have been percolating in my brain for a while – along with the Kinect-driven cat toy that rolls the Sphero around after my hapless creatures. Everything I write will be available in GitHub in the Playshop repository. I’m not sticking to 3scale APIs, anything is fair game – and if you want to contribute your own silly ideas I’d love to have them. No rules, no language restrictions, except don’t be a dick (as Wil Wheaton would say).

Come help me build a sandbox so we can turn all the developers of the world into inspired, excited builders of applications that rock all our worlds!

Posted in Uncategorized.

API Codex (previously API Alchemy)

One of my first projects at 3scale is API Codex – a centralized portal for great information about APIs around the web.  There are many fantastic articles, presentations and books available for people to learn about APIs, but nowhere for folks to find them all – until now!

I’m very excited about this, not just as a learning tool for the community, but also as a technical project – I used semantic mediawiki to create a site where you can explore the data space by tag, category or author, and we can add more ways to learn about the space based on date or other factors.  We’re looking forward to seeing how people use the site and adapting it to what people want and need.

We’ve got links to articles by industry leaders on API Design, hypermedia, business cases and tutorials. We’re always looking for more suggestions as well. If you’re wanting a quick intro to the API world, you can go directly to our API 101 page, which is a great jumping-off point to learning about the system.

Since we’re focused on APIs, I’m looking forward to adding sentiment analysis about the articles, using a link shortener API, and adding other ways to discover new great information in the space.

Take a look, contact us at @apicodex on twitter or

If you’re interested in talking to me about the semantic mediawiki experience and setup, let me know.  It’s a fantastic system and really allows for the development of an interesting semantic system.

Posted in API, Geek Stuff.


At the API Strategy and Practice conference, I gave a workshop on API 101 (slides).  I was lucky to have my actual mother in the audience so I could make “Even your mom can understand” jokes, which was great (I got her permission first, and kudos to her for letting us gently tease her in front of 150 strangers).  But also it gave me the opportunity to give a talk that even my (very smart, artistic, non-technical) mother could understand.  As I was working on the more technical pieces I realized that we have a self-referential problem frequently when trying to describe API Transactions.  We talk about parameters, headers, meta-information, requests and responses as if these terms were meaningful to a real person. Not really, no.  So, I submit the following thoughts for your consideration.

So first – what is an API? What is it like?  The easiest comparison I could come up with was the old time switchboard operator.  Your phone didn’t have to know how to get ahold of Aunt Mae, it just needed to know how to talk to the operator, and he or she would do what was necessary to connect you two.  An API is a computer version of this abstraction.

Now, for the juicy bits.  Transactions are conversations between computers.  This conversation can be boiled down to something that should amuse people who know me at all. Follow along while I describe the pieces of the HTTP Transaction like ordering an iced tea from Starbucks.

  • Resource ID: “Iced tea”
  • HTTP Verbs
    • POST: “I’d like to order an iced tea”
    • GET: “Can you read my order back to me?”
    • PUT: “Actually, make it larger”
    • DELETE: “Oh no, I left my wallet at home! Never mind”
  • Parameters: “Extra ice, unsweetened”
  • Headers: “For here or to go?”

Once you’ve walked through this conversation example you can get a little more technical – your browser uses headers to tell the server what language you speak.  Changes and substitutions are added to the name of the item.

I challenge my geeky friends to think of other ways to describe technical things without using technical terms that are meaningless to the general public.  What other examples can you think of?


Posted in Uncategorized.

Quantifying your Fitness

At OSCON last week, I gave a presentation on Quantifying your Fitness. It was well received, and most people were quite amused to see me wandering the conference with 5 fitness devices (6 if you count my iPhone). You’re welcome to check the slides out for more detailed information, but as I suspect most readers are in a hurry this post will be a summary of my findings. In some cases I don’t have all the data, so I’ll note that where appropriate and ask you, dear reader, to pass along the information if you have it. Please keep in mind that while some of these devices provide more or less information, any device that you will use and wear regularly will work great, even if it’s a simpler model. These summaries are just that, summaries. You can check the slides for more detailed information on any of these.

Ok, ready? Let’s go.


Bodymedia Fit

This is something of the gold standard of fitness devices at this time. The calorie estimates track very closely to chest-strap heart rate monitors and this device is approved by the FDA for use in clinical trials of various types. The skin temperature, moisture and three motion sensors collect 5,000 data points per minute, which they combine with some amazing backend algorithms to create a fantastic product. Price wise it’s reasonable, although the subscription price is a little daunting. The main drawback of this device is that it’s just really ugly – it must be worn on the upper arm and looks somewhat like an insulin pump. They are coming out with a new model this month (August 2013) which will look much better and also have an optional heart rate monitor – and it will be usable during swimming, which is a huge boost of coolness for this product. The website is somewhat limited – it will report your nutritional information, for instance, if you use a different application to monitor it; but it isn’t designed to be the input/tracking application for things other than the information from the device itself.


This is the one most people know – it’s a cute little device that you wander around with and it uses motion sensors to track your activity. The website is pretty darned good – you can log food, activities, mood, etc. and it will keep track of those items along with the sensor data. The API is quite strong, and has good developer support – so if you’re looking for a device/API to integrate with your cool game/application/motivational website this is a great choice. The device is easy to use, it syncs automatically when it sees the base or your phone, and it has a cute flower when you exercise. On the other hand, clipping it to your bra means you’ll wash it and have to buy a new one, so I’m on my 5th Fitbit at this point.

Jawbone Up

This device is a wristband which comes in funky colors. The headphone jack connector is supposed to be covered with a matching plastic cover, but I have kittens so as soon as I took the cover off it became one of their toys and I never saw it again. In any case, the motion sensors seem to do a decent job, but syncing by plugging the thing into the headphone jack of your phone just seems like too much effort to me (I’m lazy, so sue me :-) On the other hand Jawbone purchased Body Media recently so I expect great things out of them in the future. Their API is in beta right now, so you can’t really access your data yet… but I expect this to be fixed soon.

Withings Pulse

This device is brand new, and has gotten rave reviews. I’m not exactly sure why… it’s basically a fitbit with a few extra bells and whistles. It tracks your activity well, and has a spiffy touchscreen. You can manually check your heartrate (although I’ve found this to be somewhat twitchy) and tell it you’re going to sleep. You sync it by pushing the button on the device, which activates the bluetooth connection to your smartphone. Anyhow, it’s cool. I just don’t love it. And it doesn’t sync automatically which makes it less awesome than the fitbit. Also the website support and API interaction are pretty limited at this point, but I expect that they’ll get this fixed soon. The Withings App on smartphones does know about the pulse and tracks your activity pretty well.


I love this device. Yes, the charging cradle is a pain to use. The battery only lasts a few days, when I remember to turn off the bluetooth between syncs. But it tracks my resting heartrate every night, and the website insights and data are rockstar awesome. I love being able to look through my data how I want, and I’m looking forward to when they have an API to play with. Right now you have to get on a waitlist to get the product but I really, truly adore this device. Also, it’s a watch! Yes, it’s not exactly fashionable, but it tells the time and you don’t look like you’re wearing a medical device. The idea behind Basis is very Quantified Self-friendly – it watches your activity and then suggests habits you should try to attain – sometimes it’s going to sleep at a regular time, for some people it suggests getting up once an hour during work time. If you read out the habit suggestions in the right voice you realize that you’re strapping a Jewish mother on your wrist… not that that’s a bad thing!

The thing I love best about this device is something that’s not immediately obvious – although it isn’t great at tracking your heart rate while you’re exercising, it does a fantastic job of tracking your heart rate while you sleep. Anyone who has ever done heart rate training knows that your resting heart rate is one of the best measures of cardiac fitness – both as an indicator of general fitness (average) and a flag to let you know when you’ve overtrained, or you’re fighting sickness (or perhaps partied too hard the night before). Having this data tracked and recorded is incredibly useful, and this feature should be hailed much more widely.

Related Sites

Check out RunKeeper, who has a nice smartphone application for running/walking as well as a fantastic health graph API. If and when I create an awesome workout application, I’ll totally be using the Runkeeper API as my backend.


Bodymedia Fit Fitbit Jawbone Up Withings Pulse Basis
Price $150 + $7/month $69-$99 $69-$99 $99 $199
Heart Rate No No No No Yes
Yes No No No Yes
Sleep Auto Manual (button) Manual (button) Manual Auto
API Excellent Excellent Excellent Minimal None yet
Dashboard App + Website: Excellent App + Website: Excellent App + Website App only App: Minimal Website: Excellent
Charging Dongle/1 hour Dongle/1 hour Dongle/1 hour Dongle/ 1 hour Cradle (weird): 2 hours
Battery Life 3 days 7 days 7 days 7 days 3 days
Sync Tethered or Bluetooth (manual) Automatic when near phone, base – or manual via bluetooth Plug into smartphone (headphone jack) Manual via bluetooth Manual via bluetooth or when charging

Posted in Geek Stuff.

“Working” from Home

Telecommuting has been all the buzz this past week, with Yahoo eliminating work from home options for their fulltime telecommuters (but you can still wait for the cable guy!) and Best Buy following their lead soon after.  The articles covering these changes are quite interesting in their slant.

From Mashable, Best Buy’s announcement was spun this way:

Best Buy announced Monday that it has eliminated a flexible work program introduced in 2005 that gave corporate employees the freedom to work when and where they chose. Through the program, known as Results Only Work Environment, employees were assessed based solely on the quality of work they got done rather than whether or not they showed up to the office. Now, these employees will be expected to work a standard 40-hour workweek and come into the office “as much as possible.”

So let me get this straight.  The quality of work you do is less important to Best Buy than where you do it.  Seriously.

And in the New York Times article on Yahoo’s shift:

Parking lots and entire floors of cubicles were nearly empty because some employees were working as little as possible and leaving early.

Then there were the 200 or so people who had work-at-home arrangements. Although they collected Yahoo paychecks, some did little work for the company and a few had even begun their own start-ups on the side.

Does this strike anyone else as odd?  When you have employees who are not getting work done, you fire them.  Managers are supposed to be held responsible for the productivity of their groups.  If your managers can’t manage people except by counting the hours they’re in the office, then they should be fired as well.

I’ve been working for more than 20 years in an industry where I have to focus closely on my work sometimes, brainstorm sometimes, invent sometimes, and always be creative and alert.  Cube farms are soul sucking zombie cages where I just don’t produce nearly as much.  I am far more productive when working on my own schedule from where I want and I far exceed the output and effectiveness of most people I know.  I have a ransom note on top of my LinkedIn profile which somewhat arrogantly announces that I only want to work for people who want me to work for them.

I have fantastic skills, insight, and motivation.  I will do my best work and encourage and assist others to do the same.  I have experience in varied areas which allow me to complement those around me well.  Sitting in a seat in the office is not something I’m particularly good at, nor is it something I want to be measured on.

Best Buy and Yahoo are saying they need to rely on the same metrics used by retail establishments.  If you clock in and out on time and don’t annoy the customers, you’re doing well.  Your actual contributions to the company are not as important as your presence in the office.  How motivating is that? I can clock in, play scrabble, clock out and I should be fine.  Fortunately for my employer, that sounds horrendous to me.  I love contributing, fixing problems, helping people and getting things done.  Fortunately for me, that’s what they keep me around for.

A friend of mine pointed out how ironic it was that Marissa Meyer instituted this policy while spending the money and resources to have a nursery installed in her office at Yahoo.  Perhaps, he suggests, these struggling companies are simply trying to increase attrition to help fend off a future layoff.  If someone’s built their life structure around a particular work arrangement and has to move or find child care, they may just… leave.  And if they quit, you don’t have to fire them.  Win-win, I guess.

Posted in Uncategorized.

Happy Developers

I’ve always been all about removing barriers to help people get where they want to go.  It’s how I get gratification from my work, my play, my entire life.  This week at the amazing API Strategy and Practice Conference I’m surrounded by engaged, curious, challenging people who are committed to bringing the API world to the next level.  We’ve grown the API ecosystem organically up until now, all doing our best to meet our own goals, but being around people who have looked at this world from so many different directions makes it possible for us to see the patterns.

I spoke yesterday on a panel on API design – and I talked, as I frequently do, about happy developers. Jakub Nešetřil of made an insightful comment when he noted that we’re used to designing APIs for computers – they are, after all, programmatic interfaces. But in this world where developers are the interaction level, we have to make user interface choices. Developers are users of your API and if you don’t treat them as such they’ll be frustrated and less likely to be successful.

My talk, as always, was peppered with visual metaphors.  Developers are the wild animals out on the savannah, looking for a watering hole they like.  When they come to check out your API they’re giving you a valuable gift of something they’ll never get more of – their time.  Show them you value and respect that gift by communicating with them clearly about your product, your goals, and giving them ways to engage right away.  Play with them – provide tutorials and examples that give them a sense of progress (yes, level them up.  Game theory isn’t a bad thing.  Developers are, by nature, gamers.  Use that.)  Give them building blocks of working code, like legos so they can build new toys.  Play with your developers.  Seriously.

And support them.  Not just in the usual ways, but if you want to earn developer love, get them out there evangelizing your product, helping you support other users… teach them to be successful.  Give them tools, give them strategies, tell them how to solve the problems on their own so when they’re hacking at 3AM they can finish the toy they wanted to build.  Celebrate their successes with them because when you work with them, those successes are yours as well.

Your developers are users, yes, but they are also your peers.  They may have a different context or be coming to your system from a foreign programming world, but they want to interact with your product, and helping them to be successful is the best way to ensure the success of your own platform.

Posted in Geek Stuff.

Review: Intermediate Perl

As a programmer, I’m always looking for ways to take my coding practices to the next level. As most developers have, I’ve attended numerous conferences and sat through countless tutorials, only to find that while the topic is engaging during the talk, it doesn’t “stick” when I leave the room. The biggest exception to this was Randal Schwartz’ “Packages, References, Objects and Modules” – I attended this talk upwards of ten years ago, and it still stands out in my head as the biggest stepping stone to improve my maturity as a programmer.

This book, “Intermediate Perl” is the newest version of that curriculum, and it’s a fantastic way for someone who has become comfortable with perl but who finds themselves stuck copying other people’s code or doing things by rote because they don’t understand all the choices available to them. The book covers Perl’s reference system, which feels like black magic if you don’t understand it; it addresses ways to work with complex data and file handles, and advanced use of regular expressions. There’s also an excellent section on Perl’s OO functionality (such as it is) and testing.

As someone who has worked with perl for almost 20 years, who went through this class several years ago, I still found the book to be incredibly useful. I love Perl Best Practices, but that’s more a primer on doing things in a sensible and efficient way. This book takes the time to walk you through these concepts which are so central to Perl, from simple examples to more complex. Best of all, there are exercises at the back of each chapter which really require thought in applying the concepts just discussed. For me, this is the best way to really internalize new information – give me something to play with, some way to use it, and I’m much more likely to start using it in my own work.  Each exercise has a solution in the back of the book – and these solutions are thoughtfully explained so you understand why it works the way it does.

In short, “Intermediate Perl” is an excellent next step after “Learning Perl.”  I’d go so far as to say that it’s a good workbook for long-time Perl programmers to use – go through the exercises at the back of each chapter and see if there’s some way you can improve your coding, or something you’re doing inefficiently.  In the overwhelming sea of blue Perl books, this one provides a great set of exercises to take your development skills to the next level.



Posted in Uncategorized.

Asking Questions Well

One of the most frequent issues developers (and support people) have is that questions aren’t asked completely, and both people end up enmeshed in an iterative clarification cycle, unable to resolve the issue until both people understand what’s going on. There’s a decent FAQ on asking questions on StackOverflow, which does tell you to share details and context, but I’m going to go a little further and give you a template for asking questions which should help you get answers quickly.

What does a good problem statement look like?

I did X.
I expected Y to happen.
To my dismay, Z happened instead.

All three pieces are necessary, because frequently the problem is your expectation, not the system you’re trying to use. To clarify, let’s look at an example.

I jumped off a cliff.
I expected to sprout wings and fly across the ravine.
To my dismay, I plunged to my death instead.

Bummer. But the problem wasn’t really about gravity, it was that you expected something to magically happen to counteract it. Frequently users don’t understand how a system works, or what should be expected – this doesn’t make your question bad, by any stretch of the imagination. Part of supporting a product is making sure your users know what to expect, and the documentation may need updating. But the support person isn’t going to be able to help you if they don’t know why you think it’s broken. It may seem obvious to you what should happen, but trust me – more often than not including this piece will get you to your answer faster.

So, let’s go through this piece by piece…

I did X

When you’re explaining what you did, you need to include all the context you can.

  • What were you doing, exactly?  Can you reproduce the issue consistently?
  • Was it a web issue?  If so, which browser were you using?  Did you try other ones?
  • What exact URL or application were you using?  How can someone exactly recreate what you were doing?
  • If you’re coding, what language are you using?  Are you using a library?  Include an example of the specific code in question, with pointers to the library and examples you’re following (if applicable)
  • If you’re using a web service, what exactly did your request look like?  What were the headers and URL?  If you don’t know how to get those pieces, you need to know – read this article for some pointers.

I expected Y to happen

What did you hope to happen?  Lots of times with an error message or broken request, it’s obvious what you wanted to happen.  It’s still worth your while to include a quick statement.  But if you got a successful response that didn’t match what your expectation was, explain completely and clearly what you were expecting to get, and why.  Point to the documentation supporting your expectation (because it may well need an update or clarification).

To my dismay, Z happened instead

I try to always keep the “To my dismay…” part in there.  It amuses me, it amuses the person answering my question, and it acknowledges the truth of asking a question in this situation – I’m frustrated and sad that I’m stuck because something isn’t working how I want.

But just like with the “I tried X” part, you need to be very specific about what happened.

  • Did you get an error in a console or as a result? What did it say, exactly?
  • What did you try to get around the issue?
  • If you’re using a web service, what were the headers, status code, and/or body returned by the server
  • Note that if you are using a library that wraps a web service but asking for help from the API provider themselves, you likely need to dig down and see what the call itself looks like (as the API provider probably doesn’t support the third party libraries)

Following these guidelines will mean it takes a little longer for you to craft your question, but it will save you time, and most importantly, it will save people who might have the answer time. Posting incomplete questions wastes the time and energy of people who might otherwise help you (and they may not come back to see if you’ve added clarification). Showing them that you value their time and energy by completely explaining the issue will increase your chances of getting a complete answer – and if iteration cycles are needed they’ll be much more valuable.

Posted in Uncategorized.

LinkedIn Today SMS Notification System using LinkedIn, Twilio, Django and Heroku

At LinkedIn we enjoy a monthly Hackday, and I usually use the opportunity to figure out new ways to combine our platform with other systems – I love combining different APIs to create new functionality.

This month I decided to use my hackday time to create an SMS notification system for our LinkedIn today system. Since I’m not always on the website, I frequently miss the viral articles being discussed until they’ve passed into my history, and I’d like to be able to jump in on the conversation while it’s hot.  Using the LinkedIn Today API (currently only available internally), the system periodically checks each members feed ‘s see if there are any articles which are currently generating a huge amount of activity .  Once these “hot” articles are found, they are sent via SMS (using Twilio) to the user’s cell phone and recorded in the DB.  The member can reply to the SMS with “save” to add the article to their saved articles at LinkedIn, “share” the article with their LinkedIn network, change the notification level or cancel notifications entirely.
Welcome message Welcome message Welcome message
In order to build this system, I realized that I had to get several different systems to work together, and working through this process I realized that I had to solve several common problems.  This series of posts will be a tutorial on how to do the following:

These are building blocks that can be used for many similar projects, so I include them here to be an inspiration for future developers trying to get something working.  I enjoyed the resulting demo application enough that I ended up creating a web front-end to the system (so people could configure it) – you can get to the application at

Posted in Uncategorized.

Tagged with , , , , .