Posted by Ancestry Team on November 18, 2013 in API, Development has been operating a massive data service and website for over 17 years. As you might imagine, the needs of the business 17 years ago were much different from what they are now. Currently supporting over two million subscribers and providing access to more than 12 billion records in over 30,000 historical collections, looks quite a bit different under-the-hood now than it did when we were only hosting a handful of collections – the 1930 U.S. Federal Census being one of those.

However, some of the under-the-hood components have evolved over time. They started with a good design (for the time), and then morphed as teams, requirements, and best practices changed. As we introduced new functionality into the system, the fingerprints of the architect, developer, and technology-du-jour became evident on the interfaces for that functionality.

In short, over time, we created something of a mess.

Almost a year ago, in recognition of this challenge, we launched a platform initiative at The goal of the platform initiative is to standardize the application-facing interfaces. Why would we embark on such a project? Depending on who you asked as we kicked it off, the answers ranged from:

  • To make it harder for software engineers to do their job.
  • To provide management overhead on systems that are working just fine, thank you.
  • To force everyone to use the same development tools and languages, and you picked the wrong one for my project!

Actually, there were a few who were excited about implementing standards, but there were many who refused to believe that a standardized platform for creating new family history applications could work at After all, we’ve been doing family history software and website development for almost two decades. We must be doing something right, so why change? We had to break through the wall of resistance and help the teams understand our reasoning.

As continues to grow, we are moving away from a centralized development group. We have development offices in Utah, California, and Ireland. We’ve hired new employees and acquired companies. We have business partners. All of whom need to consume the services. We can’t afford to teach each new engineer or team how to work with all of the legacy interfaces and newly-forming interfaces.

We needed a cohesive platform for everyone to work with.

We met with teams collectively, and individually, to share the vision of the Platform. Many approached the meetings with skepticism and fear. There was active disbelief that the initiative would provide any benefits, and significant worry that it would bring more work to already busy development teams. However, as each meeting ended, most teams expressed a willingness to work with us on the initiative. Some were actually excited!

How did we turn skepticism into excitement? Clear decisions, clear and simple standards, and clear benefits for both the producers and consumers of the platform. Executive support didn’t hurt, either.

Without going into all of the details, the Platform is simply a defined way to approach software development. It embraces some simple, yet powerful, concepts:

  • APIs are interfaces, typically with client proxies. Just because you are using WCF, doesn’t mean you have an interface. Your API should be independent of the underlying transport layer. Your user shouldn’t care what happens behind the scenes. You should be able to swap out the guts of your implementation while leaving the interface untouched.
  • APIs are backwards and forwards compatible. Rolling a new “version” of the service shouldn’t break existing clients.
  • Common terms are standardized. At one point, had five different ways to refer to a CollectionId (and two different data types behind it). Now, there is one.
  • APIs are readable. No acronyms. No cryptic method names or parameters. Users should know what an API is used for and what its methods do, without having to read the documentation.
  • APIs are documented. Even though the interfaces should be useable without significant documentation, quality auto-generated documentation reduces training time for new users of the API and increases productivity for the team which owns the API. This was an eye-opener for some: time spent documenting an interface pays off repeatedly in reduced interruptions/task switching, as users can answer the basic questions on their own.

There are details to the specific standards that I won’t go into here. However, these five principles laid the foundation for the current Platform. We didn’t mandate tools. We didn’t specify a language. We didn’t force a specific interchange format.

After almost a year, how are we doing?

Today, we have a solid and growing Platform. New developers on our application teams have a consistent and standardized way to work with the underlying services. Teams maintaining the services have a cohesive set of endpoints to maintain and extend. Teams creating new services love having the standards defined – it is one less thing to worry about. They can focus on what the service does, rather than how it is presented. Teams with existing services are rolling forward with the changes. Many are creating a new aggregation layer that rolls up several of their older services with a clean API. Over time, they will swap out the underlying systems – and their clients will only see the benefits of improved performance and reliability.

The standards are evolving. We expected this. We put forward our proposal, much of which still survives. But reality and additional input have shaped and improved the standards. This willingness to work with the teams has been part of the success – teams feel it is a collaborative process rather than a mandate. Code reviews have – organically – started referencing the platform standards, so we believe we are getting close.

It’s not rocket science, but the platform initiative provides with a strong set of tools for creating new family history applications. We don’t know what those applications will be, but we know that the services will be ready.


Join the Discussion

We really do appreciate your feedback, and ask that you please be respectful to other commenters and authors. Any abusive comments may be moderated. For help with a specific problem, please contact customer service.