Rush StackShopBlogEvents
Skip to main content

The API report

This article continues the tutorial from the "What is API Extractor?" page. It's recommended to start there.

The first API Extractor output that we'll discuss is the "API report file." Since the NPM package name for our example library is @microsoft/sp-core-library, the default API report filename will be etc/sp-core-library.api.md.

The report is a Markdown file comprised mostly of a large block of pseudocode that concisely summarizes the API signatures. (Prior to API Extractor 7, the report used the .api.ts file extension, but this caused trouble for tools that tried to interpret the pseudocode as real TypeScript code.) The API report contents might look like this:

etc/sp-core-library.api.md

## API Report File for "@microsoft/sp-core-library"

> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).

```ts
// @beta
interface ILogHandler {
  // (undocumented)
  error(source: string, error: Error): void;
  // (undocumented)
  info(source: string, message: string): void;
  // (undocumented)
  verbose(source: string, message: string): void;
  // (undocumented)
  warn(source: string, message: string): void;
}

// @public
class Log {
  // @beta
  public static initialize(logHandler: ILogHandler): void;
  public static error(source: string, error: Error): void;
  public static info(source: string, message: string): void;
  public static verbose(source: string, message: string): void;
  public static warn(source: string, message: string): void;
}
```

The report file is tracked by Git. Suppose a developer makes a change to the Log class on their local PC. When they rebuild locally (for example with the --local command-line option for the api-extractor tool), they will see a message alerting them that the report file has changed:

[17:01:21] Starting subtask 'api-extractor'...
[17:01:28] [api-extractor] You have changed the Public API signature for this
project.  Updating 'etc/sp-core-library.api.md'
[17:01:28] Finished subtask 'api-extractor' after 0.54 s

The developer should commit the updated report file and include it as part of their pull request (PR). If they forget to do this, the PR validation will fail because it performs a production build (i.e. not using --local), which does not automatically update the report file. If that happens, the PR build log will show an error message like this:

[17:03:37] Starting subtask 'api-extractor'...
[17:03:44] Warning - [api-extractor] You have changed the public API signature for this project.
Please copy the file "temp/sp-core-library.api.md" to "etc/sp-core-library.api.md", or perform
a local build (which does this automatically). See the Git repo documentation for more info.
[17:03:44] Finished subtask 'api-extractor' after 0.56 s

This design enables us to define a PR branch policy that requires approval from a project stakeholder whenever a PR changeset includes the .api.md file extension. Frivolous approvals can be annoying, so the API report file is designed such that a diff only occurs when a significant contractual change has occurred.

What do we consider to be a significant change? From the perspective of a reviewer:

  • We care about changes to function signatures, but we don't want to be bothered about function bodies (i.e. every line of code)
  • We want to know about changes to exported declarations (e.g. Log and ILogHandler in the sample project), but not unexported declarations (e.g. DefaultLogHandler) or private class members
  • We care about whether people wrote documentation (e.g. presence of the "// (undocumented)" warning), but we don't need to know every time a sentence changes
  • We care about the release status of an item (@internal, @alpha, @beta, or @public), while ignoring most other doc comment tags
  • Generally we DO want to monitor @internal definitions because they affect first party consumers (but for certain classes this can be suppressed via the @preapproved tag)

Having this synopsis in one easy-to-review report is very powerful. Turning on API Extractor for a project is often an enlightening moment. ("What is THAT doing in there?! These names are pretty confusing! Why didn't anyone write documentation?!" and so forth.) Although people work with a project's source files every day, it's easy to miss the big picture without a way to visualize it.