Explore Our New API Docs
Today we publicly launched our API documentation for GlobalLink to https://docs.empiricalsecurity.com/models.global and EPSSLink to https://docs.empiricalsecurity.com/models.epss models. Our API is the primary way users interact with our data. Creating docs from scratch is a team effort. Here’s how we managed to draft, edit, and release our docs.
Our founders and engineering leadership wrote the initial draft before the API even existed. Its goal was more aspirational and helped the team plan before any development work began. After several weeks and many PRs, we had a working API. At this point, our internal docs were only shared with a few users. I researched what API docs appealed to developers and technical writers, and a theme emerged: people want up-to-date examples of API responses.
We brought clarity to our docs by adding data dictionaries for our Global and EPSS model pages. Each page organizes its data fields into related sections (ex. Scoring Data, CVE data). Each data field has a short description and example for readers. At the bottom of the page, we included JSON sample API responses too.
Now that our docs are deployed, the next steps are to incorporate user feedback. We published our docs through GitBookLink to https://www.gitbook.com/, and our examples auto-update whenever changes are made through their OpenAPI integration. GitBook’s insights feature shows what users are searching for, pageviews, broken URLs, and more. Eventually we’ll publish a new FAQ page based off common questions users submit.
