Strategic CIO // Executive Insights & Innovation
Commentary
6/3/2014
09:06 AM
Harold Madsen
Harold Madsen
Commentary
Connect Directly
RSS
E-Mail
50%
50%

Want Great APIs? Start With Training

When it comes to API development, consistency matters, training pays, and you can't be afraid of a few claws, says an Ancestry.com exec.

Have you ever tried to train a software engineer? It's a bit like bathing a cat -- think explosion, water, claws, fangs, pain.

Well, maybe it's not quite that traumatic, but programmers definitely have strong personalities and can sulk like a cat betrayed if you try to tell them how to do their jobs. Now, strong personalities are good, but they can bring challenges when an organization needs to standardize development -- and APIs are all about consistency.

My company, Ancestry.com, has awesome software engineers, products, and APIs. However, programmers are not usually trained as API designers. Furthermore, as companies build their API programs using multiple teams, APIs tend develop their own personalities and become radically different from one another. That's a problem.

Fortunately, it doesn't have to be that way. Companies can get consistency in their APIs through engineer training. If all developers hew to one set of guidelines and standards, all your APIs will feel similar.

"What's the benefit of that?" you might ask. "Why should I take the trouble to make similar APIs throughout the company? That's a lot of work, time, and coordination."

Good question. Here's my answer: Time to market.

[Marketing isn't just the CMO's job anymore -- customer engagement is key. Read IT Leaders Must Assume New Role: Marketers.]

That's it -- time to market (OK, that's not the entire answer, but I'll get to the rest shortly). It saves the company time and money when a software engineer doesn't have to learn something radically different each time he or she consumes a new API. And if a team needs to aggregate several APIs, imagine how frustrating it would be to learn each API when each one behaves uniquely.

When an API is well designed and consistent, development speeds increase, and the business shortens time to market. That's good for the company's bottom line. More importantly, it's good for customers, who get new features sooner and thus become more productive.

What's the other advantage of having API standards across teams and services? Software engineer happiness.

You might be surprised at how miserable it is to wake up day after day and have to work with an ugly API. When the engineer lifts his head off the pillow each morning, he thinks, "Oh, no, I have to use that API again." It's enough to make him want to bathe his cat instead of going to work. Worse, a miserable developer is not a productive developer, and he is more likely to jump ship.

All in all, good development standards are a big deal -- they save time and money and make for happier engineers.

At Ancestry.com, we made the commitment to spend time and money on an internal development Platform -- with a capital P -- to produce standardized, consistent, and documented internal APIs. We're proud of this effort, and we want feedback. We're also willing to share how we "declawed" this particular problem in hopes it can help others.

Platform = shortened time to market
The first order of business when building a Platform is to create the following helps and tools:

  • A platform portal wiki
  • Development standards
  • A technical knowledgebase
  • A documentation hub
  • Posters and newsletters
  • API design training

First, we created an internal portal, so developers could find all the goodies available to them. This portal is like a wormhole to nirvana. At Ancestry.com, you just type "Platform/" in your browser, and this page magically appears.

From this portal, you can teleport to other dimensions, such as our development standards, a "Getting Started" page, documentation, and more.

Second, we needed simple, consistent development standards to guide our efforts. To be consistent, we needed overarching guidelines such as URL patterns and collection naming.

Third, we needed a knowledge base

Next Page

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 histories. He has more than 20 years of experience in engineering and management and thrives on ... View Full Bio
Previous
1 of 2
Next
Comment  | 
Print  | 
More Insights
Comments
Newest First  |  Oldest First  |  Threaded View
Li Tan
50%
50%
Li Tan,
User Rank: Ninja
6/4/2014 | 4:16:26 AM
Re: Not a new problem
Thanks a lot for the clarification, gentelman. I do agree with your points - invent your own wheel when necessary by facilitating the industry standards. Sometimes the border is ambiguious but there is no need to make such kind of clear distinction - the working solition is the king here.
hmadsen
50%
50%
hmadsen,
User Rank: Author
6/3/2014 | 7:17:39 PM
Re: Not a new problem
Great question David. Let me address it this way:

What is the Ancestry Platform? It is our unified, standardized, documented service APIs. It's not a shim or a package. Simply a standard way of expressing our public interfaces. To evangelize our Platform effort, we used readymade tools such as AnswerHub, Sharepoint and other off-the-shelf document publishing tools.  Nothing was home grown but our internal APIs.

For our internal development standards, we chose industry standards. Now, industry standards (such as REST) can sometimes be ambiguous or there can be conflicting opinions on best practices. In these cases, we made pragmatic choices that helped us move forward as efficiently as possible.

Thanks again for your question,
Harold
David F. Carr
50%
50%
David F. Carr,
User Rank: Author
6/3/2014 | 1:45:01 PM
Re: Not a new problem
I wondered how much of a roll-your-own solution this had to be. Presumably, Ancestry.com took advantage of some standard software for components like the wiki, but it sounds like the overall platform was custom built. Was there really no commercial or open source platform for documentation and code repository to take advantage of, at least as a starting point? Seems like there ought to be.
TerryB
50%
50%
TerryB,
User Rank: Ninja
6/3/2014 | 1:06:40 PM
Not a new problem
Wasn't that long ago this argument was applied to writing software in general. In the very beginning, it was the "modular" versus "spaghetti code" problem, going back to green screen days. There was also focus on user interface standardization, IBM made huge effort there to make sure F3 key was used for exit when possible.

Then GUI came along, bringing many more things to standardize in the code style and the user experience. Then the web came along, adding even more, especially in user experience since you could no longer send a User Guide with your website. Then AJAX, CSS and javascript changed things tremendously in coding standards. Web services brought SOAP and REST, where API use really started to take off. Now, with the SaaS/cloud eliminating you getting source code, the API is the new "source code" most developers get to deal with now. API's are essentially becoming a programming language themselves.

I've never seen a book/tech article yet that talks about best practices in API creation. It's great Ancestry has addressed internally but this is really an issue that needs to standardize across everyone, like the idea that modular top down code was better then spaghetti branching all over the place.

I wonder if API's are the final solution anyway. I tend to think this might morph into what goes on in OOP, where you can take a base class and extend it with much more functionality. Then we'll get back more what source code offered over API's.
The Business of Going Digital
The Business of Going Digital
Digital business isn't about changing code; it's about changing what legacy sales, distribution, customer service, and product groups do in the new digital age. It's about bringing big data analytics, mobile, social, marketing automation, cloud computing, and the app economy together to launch new products and services. We're seeing new titles in this digital revolution, new responsibilities, new business models, and major shifts in technology spending.
Register for InformationWeek Newsletters
White Papers
Current Issue
InformationWeek Tech Digest - August 27, 2014
Who wins in cloud price wars? Short answer: not IT. Enterprises don't want bare-bones IaaS. Providers must focus on support, not undercutting rivals.
Flash Poll
Video
Slideshows
Twitter Feed
InformationWeek Radio
Archived InformationWeek Radio
Howard Marks talks about steps to take in choosing the right cloud storage solutions for your IT problems
Sponsored Live Streaming Video
Everything You've Been Told About Mobility Is Wrong
Attend this video symposium with Sean Wisdom, Global Director of Mobility Solutions, and learn about how you can harness powerful new products to mobilize your business potential.