VikingCloud: documenting your security API as you build it
How a leading cybersecurity AI company built their first general audience API at the same time as their developer portal.
There’s a ‘documentation divide’ intrinsic to API innovation: a gap between building APIs and keeping their docs up to date. This story is about that: about a valiant cybersecurity provider, VikingCloud, whose developers wisely chose to mind-that-gap before even writing a line of JSON:
- Jon
Let’s learn about their experience from Jon Marler, the company’s Product Admiral. Give it up for Jon, and see you all in Valhalla! ⚔️
Product Admiral
Background: building docs while building API
- Jon
VikingCloud is a cyber defense SaaS that makes protection against cyber threats proactive and continuous. They specialize in network infrastructure, compliance, and assurance testing and assessments.
VikingCloud’s flagship product is the Asgard Platform™, an AI-based tool that continuously monitors cyber threats and collects security alerts in real time, processing more than a billion security events a day.
To-build list: Asgard API 1.0
Jon’s team was tasked with creating an API to complement the Asgard Platform’s powerful dashboard and workflows. And to make sure customers would use it, they needed better developer onboarding than what the security industry is all too accustomed to:
- Jon
These kinds of PDFs are expensive to put together, and they have to be updated with every change, no matter how small. That’s why our vikings knew they’d have to dynamically document their API from day one, and educate their customers in a simpler and more timely fashion.
Requirements
- 100% OpenAPI spec
- Docs rendered automatically
- Docs auto-update when API changed
- Turnkey developer portal solution
- Bonus props: one source control to rule 'em all
Auto-docs from OpenAPI
To build their API, Jon and team settled on the most popular specification, OpenAPI (OAS). And ease of documentation, turns out, was one of the decisive advantages:
- Jon
Jon got down to researching methodologies and products, and amongst the tools that could render OAS into API docs automatically, one stood out: Yours Truly, Redocly.
OAS into docs, easy as cake 🎉Docs-like-code from day minus-one
Building and documenting APIs at the same time is an approach known as docs-like-code, and it’s our design philosophy and point of pride here at Redocly. By making this strategic choice, the VikingCloud team kept their whole API pipeline in one place and saved a bunch of very limited developer time.
“Turnkey” developer portal
Redocly’s architecture is unique in that it uses the API registry as a single source of truth, which leverages the standardized format of API definitions to render fully functional developer portals out of the box – what Jon calls a “turnkey solution.”
Being built directly from the API definition — which, if you’re doing things right, changes often — the portal is always up to date. And it’s easy to get a v1 out and kicking with portal templates.
- Jon
BitBucket CI pipeline
The engineers building the Asgard API also love using Redocly in their day to day. They connected Redocly builds to their CI pipeline with a native BitBucket integration, so they can publish straight to Redocly with every production update.
VP of Engineering at VikingCloud
Here’s how their pipeline looks like day in, day out:
Code-first API building approach
Push API and docs to BitBucket
OAS 3.0 definition updated in Registry
Developer portal auto-updates
The plot thickens: acquisition & rebrand
To make matters more interesting – at least to you, dear reader – VikingCloud’s first foray into public APIs happened in the middle of a major acquisition. Jon and the Web Risk Monitoring service were part of SecureTrust, a company that VikingCloud acquired in 2020.
Acquisitions usually imply months of migrations, code refactoring, and a code-spaghetti of Zoom meetings. But when it came to their API developer hub, Jon and team were all settled:
- Odin
Namely, Redocly makes it easy to change your developer portal theme, and style individual elements as you see fit with just a few lines of code. And just like that, the before becomes the “after” in the blink of an eye:
How VikingCloud is using Redocly
Asgard Platform developer portal
Custom-designed developer hub launched in record time from API definitions.
BitBucket CI with Workflows
One CI pipeline to push API docs to prod with every update to the API definition.
API Reference docs
For Asgard core services and Web Risk Monitoring (WRM) APIs, neatly integrated with the portal.
Making security easy to document
Our mission at Redocly is to accelerate API ubiquity — and no matter how simple the use case, or early the stage of production, static PDFs are not the way to get there.
Our friends at VikingCloud were forward-looking enough to understand that documentation and developer onboarding should be a key decision factor in your API journey. By embracing docs-like-code from day zero, they bypassed the struggles encountered by some of our customers:
- Some use in-house documentation tools until they become unwieldy to maintain (see Australia Post or Checkr)
- Others use less flexible third-party API docs tools from the start, then switch to Redocly to expand their feature set (see Brex) or to launch more customized developer experience (for example, Sinch)
Building your first API can be a daunting task, but if you start with a documentation pipeline firmly in place, a big part of the job is done, dusted, and off your to-build checklist. So, kudos to our Vikings — and see you in Valhalla!