Posted by on March 3, 2014 in API

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.

Family in Africa

Several pictures of me and my family in Africa

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 familieshang with me here and let me explain (yeah, call me a nerd – it’s true).

Mobile app using Ancestry API

Mobile app using our API

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.

Doors with bad design

www.baddesigns.com

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.

Family picture

My family

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.

Princess Bride - Let me explain

Princess Bride (www.shanelien.com)

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.

 

About Harold Madsen

Harold Madsen directs the APIs at Ancestry.com, the world's largest online family history resource with the mission to help everyone discover, preserve and share their family history. He has over 20 years’ experience in engineering and management and thrives on creating clean, easy to use and accessible APIs. Harold manages both internal and external APIs at Ancestry.com. His most recent endeavor involves leading the Company’s effort to redesign the internal APIs based on high internal standards and a unified presentation layer across all teams, stacks and departments.Harold enjoys hiking and camping in his free time and has hiked 10 mountain peaks and climbed one pyramid in Egypt. He is also distantly related to John Lackland, king of England of the Robin Hood legends.

2 Comments

Kiah Hochstetler 

Harold,

On my exploration for and API that I could leverage Ancestry.com data through I have just received a lesson on parenting and the value of children & life experiences. Wow! I take my hat off to you in pulling me away from my business endeavors to look at life itself.

My team recently interfaced with one of those “Oh no! I have to go to work and use THAT API,” for the last 8 months for some major accounting software & I know their days would have been better if they were able to wake up and develop for an API based on your methods. Thank you for caring about API quality and making developing life more enjoyable.

I’m looking to utilize Ancestry.com data for a new project but have had little success finding out when and if you will have an API available to the public through your customer service department. If you have time or more information it would be much appreciated and I look forward to working with one of these beautifully crafted APIs.

Happy Saturday
Kiah

April 5, 2014 at 4:34 pm
    Harold Madsen 

    Hi Kiah,

    Thank you for your kind post Saturday. API designs really do impact our lives in good or poor ways don’t they. Just a little bit of forethought can go a long ways.
    Regarding your question about an Ancestry.com API, at this time we do not have a publicly available external API. I wish you the very best in your API efforts and projects. May they be richly rewarding.

    Warmest Regards,
    Harold

    April 7, 2014 at 4:54 pm

We really do appreciate your feedback, and ask that you please be respectful to other commenters and authors. Any abusive comments may be moderated.

Commenting is open until Monday, 17 March 2014