Projects > API Extractor

API Extractor logo

API Extractor is a neat tool for managing API contracts for TypeScript projects. The inspiration came from working on SPFx, which is an SDK that allows customers to build TypeScript plugins for SharePoint websites.

With SPFx we faced an unusual challenge: Suppose a customer spends a bunch of money to build a custom plugin. They deploy their plugin to the web site. It may work fine for months or years, without ever needing any fixes. During this time, SharePoint is constantly pushing out new builds of the application, including updates for the plugin framework bundles. The customer doesn’t control when these upgrades occur. Everything depends on the plugin API contracts being stable, similar how an OS upgrade must never break your apps.

For example, say someone comes in to the office one morning and finds that their sales report won’t render. But the sales meeting is tomorrow! They rush to track down whoever made the plugin, perhaps a contractor. The developer needs to dig up the old project, debug the problem, make a fix, and deploy an update. There’s overhead in remembering how to do that, and potential delays if the deployment needs a signoff. They would be understandably upset if this fire drill turned out to be caused by an API break!

This sort of rigor is fairly alien to the fast paced world of JavaScript/TypeScript, though: The state-of-the-art is SemVer, which carries an implicit philosophy that APIs are free to change at any time, as long as the version number reflects it. If we accidentally ship a breaking change, it’s not thought of as a big deal. Tell the developers to temporarily downgrade, then fix their code. But that philosophy clearly won’t work for a dynamic linking system with unbounded backwards compatibility.

When we tried to explain this SPFx requirement, it sounded like crazy talk. People thought it could never work — JavaScript is just too brittle! But non-web frameworks have been doing that for decades. The challenges for JavaScript turned out to be solvable engineering problems. A big part of it involved introducing a human “API review” workflow.

Tracking API contracts is tricky in TypeScript, it turns out. This led me to the idea for API Extractor. It’s a tool that consolidates the API signatures into a single file, designed to facilitate a human review process. It also formalizes what is supported for customers, e.g. allowing individual members of a class to be marked as “internal” or “beta”, while others are “public”. Later we added support for generating documentation websites.

API Extractor is one of the most fun projects I’ve ever worked on:

- It involves some really challenging algorithms and data structures.
- It’s something that many people can use.
- And as far as I know, it was the first tool of its kind for TypeScript.

Pretty rare to find all that in a single project! I was so excited about it that I eventually got the team to release it as open source, so others could benefit from it.

The code: