Want Great APIs? Start With Training - InformationWeek

InformationWeek is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them.Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.

IT Leadership // CIO Insights & Innovation
09:06 AM
Harold Madsen
Harold Madsen

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
We welcome your comments on this topic on our social media channels, or [contact us directly] with questions about the site.
1 of 2
Comment  | 
Print  | 
More Insights
Newest First  |  Oldest First  |  Threaded View
Li Tan
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.
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,
David F. Carr
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.
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.
Reflections on Tech in 2019
James M. Connolly, Editorial Director, InformationWeek and Network Computing,  12/9/2019
What Digital Transformation Is (And Isn't)
Cynthia Harvey, Freelance Journalist, InformationWeek,  12/4/2019
Watch Out for New Barriers to Faster Software Development
Lisa Morgan, Freelance Writer,  12/3/2019
White Papers
Register for InformationWeek Newsletters
Current Issue
The Cloud Gets Ready for the 20's
This IT Trend Report explores how cloud computing is being shaped for the next phase in its maturation. It will help enterprise IT decision makers and business leaders understand some of the key trends reflected emerging cloud concepts and technologies, and in enterprise cloud usage patterns. Get it today!
Flash Poll