I’ve presented at several conferences recently and one of the analogies that resonated with the audience was that of comparing API Design to parenting. So, here’s the analogy: APIs Are Like Parenting…
The year was 1966. My family was living in Ethiopia while my dad taught at the American university as a guest professor. I awoke one morning to hear my dad rousing the family at 6am for “Family Morning”. My dad would walk through the house singing his wakeup song and gathering the family to read children stories and scriptures. Then we would say family-morning prayer and enjoy my mom’s hot breakfast. As a young child, I have to admit it was pretty annoying to wake up so early in the morning, however, looking back now it is a cherished memory.
It wasn’t just the exotic world of Africa with servants, a pet baboon and visits to the Tisisat Falls (Blue Nile), for example, but the enjoyment of family activities too. In fact, I think these family events, along with other family traditions, are what makes our family so tightknit. Even after 40+ years since our 4-year African adventure, we still enjoy hanging out together.
My family experiences have had a huge impact on my life. My parents were not perfect, but were kind, gentle and incredibly consistent. In my mind, that consistency makes a big difference in the success of a family. Recently I was preparing a presentation on APIs when it occurred to me that designing successful APIs has surprising commonality with raising successful families – hang with me here and let me explain (yeah, call me a nerd – it’s true).
Like most technology companies, Ancestry.com has many APIs. What’s an API you ask? Well, in a nutshell, it’s what programmers use to create a computer application. For example, Ancestry has some really awesome mobile applications. These mobile apps show your family tree with relationships, events and photos. How does that app get your family tree from Ancestry? It uses the Ancestry API to programmatically and securely access and update your family tree. It’s pretty cool stuff.
Developers create APIs of all kinds, and depending on their design skills, the API can turn into something easy to use or difficult to use. Let me digress and explain this a little further. There is a concept called Design Affordance. Design Affordance says that the way an item (such as a door or a filing cabinet) is designed communicates how it should be used. The design of the item speaks louder than the documentation. Take these doors in the picture to the right for example. The design of the door is quite poor. It’s so poor that instructions were placed on the door to help the user know what to do. The design can be good and helpful or poor and a hindrance. At Ancestry we promote good API designs so they are intuitive and easy to use. That way we can more quickly build products for our customers.
So, how are APIs like families? I promise, I’m getting there. Just a few more words about families to properly demonstrate the analogy. I’m not a parenting expert but I think I have a pretty good nose for the topic now that I have raised several children of my own. Parenting is so rewarding! And challenging too! It’s just a lot of work mixed with fun and rewards. But now that my kids are mostly grown the rewards are rolling in big time.
I love hanging out with my adult children (half are married now). They are such great people and terrific friends. We have so much fun together. We look for any excuse to have a party with food and fun and just be together. But getting to this point took a lot of work, love and consistency.
As I look around at other families that also have success, I notice they have different parenting styles from me and yet their children turn out fine too. So is there any connection between successful parents? Maybe. I think the connection between most successful families boils down to love and consistency. If you spend time with your children, enjoy them, love them, have patience and are consistent with your rules, punishments and rewards then it usually works out. Certainly there are no guarantees but these things help.
So now the tie in. Successful APIs are like successful families in the sense of attention and consistency. It takes a lot of love (attention) and consistency to create an API that is easy and fun to use.
I’ve got a presentation that explains how to design awesome APIs but I’d need an hour. But as Inigo Montoya said in the movie Princess Bride, “Let me ‘splain. No, there is too much. Let me sum up.” OK, “let me sum up” a few things that make for a great API:
- Consistent naming conventions
- Standard terminology
- Uniform error responses
- Attention to detail (that’s the love part for APIs)
- REST APIs that work with only 2 resources and use 4 HTTP verbs (oh, there is so much more to talk about here…)
- Avoid API design by way of method-driven approach – that leads you down a slippery slope
It’s really hard to sum up good API design in a short blog, but the bottom line is to be consistent. Stop and pay attention to the API designs, make sure they are consistent throughout and take pride in the results and in good, discoverable documentation. If you do, then developers will thank you for caring and your API is more likely to be used. They are more likely to wake up in the morning and rather than say, “Oh no! I have to go to work and use THAT API,”, they will say, “Yes! I get to go to work use that awesome API!”
What successes or challenges have you had with good or bad API designs? Leave a comment and let me know.