When developing a solution, one of the most critical elements to get right is establishing the proper line of communication between the developer and the user. Communicating intent and establishing a modality for long-term collaboration is key to ensuring a healthy product and community. One of the best things you can do to make this a reality is to invest in proper documentation.

There is a major hidden benefit to documentation, however, that is often missed — in many cases, documentation can play a key role in delivering effective API security. In this piece, we’re going to look at exactly how documentation does this and what the overall function of documentation within a security posture looks like. We’ll offer some best practices for effective documentation and provide some actionable insights you can take to any organization.

5 Ways API Documentation Benefits Security

Good documentation can improve and reinforce API security. It enhances knowledge sharing within a developer community and facilitates audits. It’s also helpful for training purposes and in pinpointing potential application risks. Here are some key ways that maintaining active API documentation can benefit cybersecurity at large.

1. Improves Clarity and Understanding

Solid API documentation provides clear and accurate descriptions of what each API endpoint does, allowing developers and security teams to better understand the expected form and function. This prevents misunderstanding and assumptions that can lead to misuse of API endpoints, which drastically harm API security.

Documentation also sets an understanding of the API’s limits. A lot of API issues arise from using systems outside their intended design. Knowing an API’s full capabilities can help assess when “too far” is actually too far. It can also help users understand what security measures are needed and reinforce those requirements.

For instance, if an API can access sensitive data, it would require stricter security controls. Yet, if this is not documented, the user may never have any way of knowing this requirement.

2. Helps Identify and Mitigate Risks

Investing in detailed documentation helps developers identify and highlight potential security vulnerabilities within an API. For example, if the documentation specifies data validation rules, it’s easier to spot when these are not being enforced. The very effort of documenting these security issues can help developers understand their own codebase better, thereby leading to better outcomes.

Documentation can also dramatically improve consistency and accuracy at scale. Documenting security features, like authentication methods and access controls, ensures they are used correctly and consistently. No comparison can be drawn without a baseline for the correct use and methodology, hampering efforts to improve and enforce security.

3. Can Facilitate Audits and Compliance

Proper documentation can serve as a document trail for security audits, ensuring that all aspects of the API have been reviewed and are compliant with security standards. This can apply both internally and externally — as an internal effort, it can help guide the security efforts of the overall system, but for external users, they can also provide a framework for developments based upon your API.

Comprehensive documentation also significantly helps with regulatory compliance. For APIs subject to such requirements, such as those processing PII or banking information, documentation can help demonstrate that compliance efforts were undertaken and can help lay a solid foundation for any economic or legal ramifications should an external issue (such as a third-party library exposure) occur.

4. Prevents Unauthorized Access

APIs are best secured with the principle of least privilege, wherein a user only has access to the minimal amount of systems that are needed to do the work they are allowed to do. This requires a lot of legwork, and clearly documenting who has access to what parts of an API within documentation can help.

This is also a prime opportunity to go through authentication and authorization frameworks and mechanisms to ensure that there is a documented state of proper configuration. Documentation that includes setup and configuration guidelines helps avoid misconfigurations that could lead to security loopholes.

5. Enhances Training and Awareness

Quality documentation is essential for training new users and making them aware of the security aspects of the APIs they are working with. Documentation can greatly aid this effort and raise awareness of issues the developer knows exist within the codebase.

A good user base is an informed and trustworthy user base. Documentation can deliver that if you properly invest the time and effort in its creation. Good documentation facilitates a clear understanding of the API and how it interacts within the systems it interacts with. Any improvement in user understanding will pay huge dividends, and documentation certainly delivers that in spades.

What Makes Good API Documentation?

Now we know the benefits of maintaining active API documentation within the context of security, what are some tips for improving said documentation? Well, a few key attributes can significantly improve the quality and usefulness of API documentation.

Good Documentation is Clear

Documentation is, at its core, a line of communication between the developer and the end user. Accordingly, the clarity of this documentation will determine the efficacy of the effort. Documentation should include a clear, high-level description of the API, its core features, and its intended use cases. It should clarify the current state of the API, including the version and any prerequisites for use, and offer a clear pathway for getting started.

Documentation should provide detailed information about endpoints, the URL structure, relevant parameters, and type limitations that the average user may encounter. Err on the side of over-documentation — it’s better to document too much than too little.

Good Documentation Provides Examples

Effective documentation should provide ample examples of how the API works in practice. It’s not good enough to just say “this endpoint exists” — you must provide examples of how it actually works in production. Provide example outputs and examples of when the API might fail due to server or user errors.

Remember, the purpose of documentation is to train the developer consumer so they understand. Treat your documentation as if it is a textbook on the subject of your API, and provide as much as you can to get the user up to speed in a reasonable timeframe.

Good Documentation Outlines Your Security Posture and Approach

Provide clear information and instructions about how you secure your systems. Provide definitions and examples of how to authenticate and authorize calls, and explain how the flow you utilize works and how it might fail.

Step-by-step guides at this level can help establish secure postures for anyone using your API. The better you document your security posture, the easier it is for others to replicate and propagate, establishing a baseline security approach that makes the whole system that much more secure.

Good Documentation is Specific

Provide ample documentation for things like error handling, rate limits and quotas, governance issues, compliance and security considerations, and data privacy. You never know what assumptions the developer user might make, and by providing these answers, you can avoid issues that may arise.

Establishing norms and policies in documentation can go a long way toward improving the overall ecosystem, so take your time to set your expectations in form and function.

Good Documentation is Community-Centric

Documentation is meant to be used by users. Provide as much as you can to be community-centric. This includes providing contact information for support, enabling forums or other community communication features, fostering discussions related to documentation, and even detailing how to contribute to the overall project.

Your community is an engine for change and better iteration. Ignoring the community is making the assumption that only the software provider knows what they’re doing — this ignores a huge potential source for helpful feedback. Prioritize the support of your community now, and you can reap dividends over a large scale of time.

Good Documentation is Accessible

Good documentation should be accessible. Remember that since your users can run the gamut of creeds, nationalities, beliefs, and abilities, your documentation should be inclusive. Accessible documentation means providing translations and accessibility enhancements, such as increasing the text size, using color-blind-safe color palettes, and avoiding flashing patterns.

Remember that you want documentation to be used by as wide a swath of users as possible. Ensure that you are supporting these users, and they will be more likely to actually use your tools.

Good Documentation is Searchable

Finally, utilize effective navigation and logical structures to make your documentation easy to navigate and peruse. Users will ignore documentation if they can’t search through it and find the issues they need to resolve. Search functions can help significantly in this area. Still, even tools like Swagger or Postman, which allow for direct connection to documentation from the API, can help in surfacing this information.

Ultimately, you need to ensure that users seeking answers can actually find those answers — anything short of this is bad documentation.

Real-World Examples of API Breaches Resulting from Bad Documentation

The role of API documentation in cybersecurity isn’t just smoke and mirrors. There are two very good examples of where poor documentation had an impact on data breaches and exposures.

The first one that comes to mind is Uber’s 2016 data breach. In 2016, Uber suffered a data breach that exposed the personal information of 57 million users and drivers. This breach was partially attributed to issues with how API keys were handled, specifically the fact that an API key for Uber’s AWS account was available via a private repository in their GitHub. Because GitHub was not protected by two-factor security, an attacker was able to break into the account and exfiltrate the credentials. Improper documentation practices and security oversight provided attackers with access to Uber’s AWS infrastructure, leading to the data breach.

Another example of what has been called a “quasi-data breach” is the Cambridge Analytica scandal. Starting around 2014, Cambridge Analytica misused Facebook’s API to harvest the data of millions of Facebook users without their consent. Part of the issue was attributed to poor API usage policies and controls, and especially lack of clarity around these policies in partner documentation.

Final Thoughts

Good documentation is relatively easy to create, and investing time and effort into this part of the process can pay off in a huge way over time. Investing in proper API documentation can improve your API security by leaps and bounds and should be considered a critical part of any product lifecycle.