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. The developer might be an employee or external contractor. Once they’ve deployed their plugin to the web site and stabilized it, it may work fine for months or years, without ever needing any fixes. But during this time, the SharePoint service is constantly rolling out new releases, including updates for the plugin framework bundles. The customer doesn’t control when these upgrades occur. If a framework change breaks the plugin somehow, that would be bed.

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 the contractor. The developer needs to dig up the old project, debug the problem, make a fix, and deploy an update. 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: The state-of-the-art is SemVer. It embodies an implicit philosophy that APIs are free to change at any time, as long as the version number reflects it. If a break occurs, no big deal. Tell the developers to temporarily downgrade, then rewrite their code. This philosophy clearly won’t work for a dynamic linking system with unbounded backwards compatibility.

When we tried to explain this SPFx requirement, people balked at it. JavaScript doesn’t work that way! But non-web frameworks have been maintaining stable contracts for decades. OS’s are particularly good at it. It’s a solvable engineering problem, even for JavaScript. The most important part was introducing a human “API review” workflow.

Tracking API contracts is tricky in TypeScript, however. API Extractor helps by consolidating 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.
- 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: