The nights are getting darker and the shadows are growing longer. The rattle of dry leaves has replaced the sound of the chirping crickets. It’s spooky season, and the scariest threat of all is the unknown!
That’s why it’s time to talk documentation. Bad docs aren’t only a productivity pain point, they can make you more vulnerable to cyberattacks and slow you down at crucial moments. Poorly documented APIs are the source of plenty of horror stories – you could probably tell a few tales of your own!
What you might not have realized is that you can learn a lot on how to make it through the chilling maze of documentation from the survival “rules” for horror movies!
Get the Blueprints
Have you ever tried to escape from a haunted hotel without knowing the floor plan? Or barricaded yourself against the zombies in an abandoned mall with no map of the entrances? How about implementing safe data segregation when you have incomplete API docs?
Another way to frame it: the greatest risks are the unknown unknowns.
You may think you’ve checked every item off your list, but if the list itself is incomplete, you’re almost certainly overlooking important risks. When you include documentation in your API development process, you gain a built-in audit tool helping you map your risks and create more robust API products and integrations.
The external risk landscape is always changing. As new threats materialize, it’s crucial to understand what your risk exposure is. You don’t want to have to re-learn your landscape or spend precious time trying to figure out where you’re vulnerable.
Good documentation is like a map, but the process of creating the map has its own benefits. As your teams create your “maps”, they should pay attention to some key security factors:
- Do you have consistent, rigorous data segregation? Where is sensitive data located, and where should it absolutely not be exposed?
- What are your preferred auth practices? Are you following them consistently across all resources?
- Do you have a clear way of tracking dependencies? Are you using automatic patching and updates? If not, how are you ensuring your dependencies stay current?
When you create your security incident response plans, you should be able to make a definitive list of your exposures. The process of creating documentation will help you get there. When the time comes, those docs will give you the confidence to respond quickly.
Make Sure the Zombies Are Really Dead
If you’ve ever seen a zombie movie, you know the real danger comes after you think the zombies are dead. The threat can keep morphing and growing long after you think you’ve put it to rest. They always come back!
The same can be said for zombie APIs, those old versions and abandoned projects still hanging around. Unmanaged APIs make up more than 50% of all APIs. You may have directed users away from deprecated versions long ago, or abandoned a project before it ever got to production, but any endpoints facing the public web are still a risk, especially if you’re not looking at who’s accessing them. Outdated SDKs are a common source of traffic to unmaintained resources, as well – you need to think comprehensively about where traffic to your APIs may be coming from.
We’ll say it again – the biggest risks come from the unknown. If you’re not actively maintaining an online service, whether an API or something else, you expose yourself to unnecessary and unknown risks. Ideally, you should be only maintaining essential APIs, and phasing out any “zombie” APIs within six months.
So how does good documentation help you ensure you’ve killed off zombie APIs and contained the risk?
For one, it’s imperative to have a single source of truth listing any and all public endpoints you maintain. Automating a list of endpoints is a start, and there are audit tools to help you do it. You can re-run the audit on a regular basis to ensure sunsetted services have been taken down.
Once you have a definitive list of all your APIs and endpoints, you’ll want to integrate that list with the kind of information we discussed above. How will you know about dependencies or sensitive data exposure? Who will be responsible for monitoring that information and turning it into useful documentation?
Sound documentation practices can also help you monitor the scope of your API programs, provide a clear view of the consequences of sunsetting APIs, and communicate changes transparently to stakeholders and consumers. Different job functions in your organization will need different details and contexts from each other and from external API consumers, but ensuring they all draw from the same single source of truth is crucial.
Service the Car and Pack Supplies
You’re panicked, running out of time to escape, but you have a car! It’s a horror movie, so you can guess what happens – the car won’t start. Or you forgot the keys, you’re out of gas, you’ve forgotten something important and have to turn around…
No one plans to be unprepared. Being prepared is an active, conscious process though. Ask yourself two questions to evaluate your readiness efforts:
- How do we systematically track our dependencies and third-party tools?
- How do we consistently turn individual knowledge into institutional knowledge?
API sprawl leaves more opportunities for things to be out of order when you need them. The middle of an active cyberattack isn’t a good time to find out that you’re using different auth patterns on different resources. A production outage is not when you want to discover that you’re using unmaintained dependencies, or that you don’t know which version of your API is being used by which customers. You need a clear accounting of your dependencies, capabilities, and limitations so you can fix problems before the crisis and act decisively when it does happen. What tools or practices do you have to audit your documentation? Are you confident you have complete records of your service architecture and product functionality?
Organizational sprawl can have similar consequences to API sprawl. When one or two people hold critical knowledge, you can’t count on having access to that information in a crisis – it’s a particularly common problem in organizations growing rapidly or where job functions are highly siloed. How confident are you that crucial knowledge is getting written down and indexed so it can be found quickly in a crisis? Integrating documentation into your development and QA processes helps ensure information is available when and where it’s needed.
Always Stick Together
The number one rule for horror movies: never, ever go at it alone. Did you know it’s a rule for your API documentation, too? Not every company can afford dedicated technical writers, but even a less specialized team will still deliver more valuable docs than what you’ll get from any solo effort.
Documentation is a discipline with well-researched practices and specialized tools. Ideally, you’ll find an experienced technical writer to lead your documentation efforts. Even if you can’t though, you’ll want to build a team with some of these strengths:
- Technical knowledge: The documentation process should be a “sanity check” on design and implementation. You’ll get the most value from a review by a technical peer of the development team.
- Customer perspective: Developer advocates, product managers, and support engineers will all have important insights into what API consumers need to know.
- Writing skills: Documentation needs to be concise and accurate. Even better if it’s engaging. Good writing takes practice, so you’ll want team members who have prioritized those skills over time.
- Information architecture: Creating information is only half the battle. Organizing it so that it’s useful is just as important, and not always intuitive. Depending on the scope of your docs, you may need more than what you get with out-of-the-box documentation tools.
Be careful of over-relying on one person to handle documentation, or of making engineers responsible for their own docs. If you want useful documentation, you’ll need to make it a team effort, and if you want it to be sustainable, you’ll need to share the workload. If you can make documentation the norm and share the work, you’ll reduce the burden on individuals and increase buy-in. No one wants to wander off into the dark alone, and you’ll be stronger and safer when you work together.
Stay Alert
We need to add two final rules for survival: never turn your back on a threat and never say “I’ll be right back!” In other words, vigilance is crucial. You’ll need to practice vigilance in a few ways.
Automated documentation is a terrific addition to your toolkit, but you know not to let the robots go unsupervised, right? We’re pretty sure your physical safety isn’t at risk from automated docs, but you still need human oversight. If you need engineers to peer review each other’s work, you certainly need the same level of scrutiny for work produced by automated tools. The tools aren’t perfect, so you’ll need to monitor for errors. You may also find the tools pick up inconsistencies that human review overlooked, and that show up more clearly in the docs than in the code.
We know you have a lot on your plate, and it’s easy to think documentation can wait. The graveyard of abandoned documentation projects is as full as any horror-movie cemetery though. Documentation needs to be created in a timely way or it likely won’t get done, since there will always be something that feels more urgent. That’s why building processes and frameworks that make documentation easy are worthwhile. Once they’re established, keeping up with changes will be much easier. Just don’t let it slip out of view, or the ugly threat of zombie APIs may come creeping up when you least expect it!
You never want to turn your back on a threat. The security landscape is always changing, and you can’t afford to let events pass you by. There’s no reason to panic, even though we can’t predict what tomorrow will bring, you have the resources and knowledge to prepare for the unknown. Take a look at your documentation efforts this Halloween – if you stay alert, build a team, and plan ahead, you’ll be ready to face even the spookiest of threats!
