API Reports

[00:00:00]
>> Mike North: So we've made some changes and we can run the report again and take as a given that some of these have gone away. Now I want you to look at another folder that was created here. It's this temp folder. So what we have here is this thing that I referred to as an API report.

[00:00:29]
Here's what it looks like. This is the API report. This is a markdown file, if you commit it to GitHub, it will render beautifully on the website and it shows exactly what is being exported from this module. It also encodes warnings. So there's a lot of stuff here, this is a complicated type.

[00:00:52]
Now I want you to imagine you're reviewing a pull request and instead of having to piece through and see like you've changed this type and it is used in a function signature that happens to be public. But where you change this type is like deep in some internal code having something that's so clear to see that's sort of a roll up of the exposed API surface of this library is super useful because you can just see it in terms of a diff here.

[00:01:23]
It becomes clear as day whether whatever you changed in a pull request has ripple effects that downstream users of the library will feel in a way that is either breaking or non breaking. But that's a good reason to bake something like this into your build process or to build a bot around it so that it comes into a pull request and says here's the updated API report makes it super, super clear to spot when a given code change has ripple effects that affect the library's outer surface.

[00:02:03]
There's another file here, it's called Models API JSON and this is going to lead into our next topic where we talk about generating API documentation based on this.