API documentation’s critical role in securing your APIs
by Kon Akopov
APIs (Application Programming Interfaces) play a key role in modern application architecture. They provide a set of methods and functions that enable different applications and services to exchange information and interact with each other. APIs act as a bridge between different system components and allow these systems to work together - even if they are developed in different programming languages or use different technologies.
The nature of APIs makes them inherently vulnerable and a prime target for hackers who may attempt to exploit misconfigured or unprotected APIs to inject malicious code, launch attacks on the system itself, or gain unauthorized access to sensitive data (as in the case of the 2022 Optus data leak).
Benefits of centralised API repositories
Consistent and appropriate implementation of authentication, authorization, and data encryption are an integral part of protecting APIs and ensuring system and data security. Moreover, in the face of increasingly sophisticated and more frequent attacks, having a centralised repository of information about the APIs within a company is crucial. And such information can be highly valuable. Unfortunately, this aspect of API security is overlooked by many companies.
Here are a few reasons why a centralised API repository is so valuable:
- Documenting APIs with detailed instructions and information on how to use them, what requests to send, and what data to expect in response allows security engineers to perform deeper security testing of APIs and to identify potential vulnerabilities.
- Documented APIs play a vital role in quickly identifying and resolving issues related to the availability and functionality of services. In the event of incidents or failures, operations support engineers can refer to API documentation and quickly determine which APIs and associated services may be unavailable or experiencing problems.
- Software engineers can see the existing APIs available for integration with various services and system components, rather than building functionality from scratch. This significantly reduces development time and simplifies the application creation process.
ANZ’s centralised API inventory solution
There are many practical ways to build a centralised API repository. Fortunately for us, a team within ANZ has been working on a solution for a while now. When the team encountered the inevitable questions around scalability and wider enterprise adoption, they came up with a novel approach. Their solution was to use our open-source project, Sysl. Yes, you heard it right – ANZ actively contributes to the open-source community and is actively developing and utilizing Sysl!
Sysl is an open-source systems modeling language and toolset that helps software developers and architects design, document, and generate code for complex software systems. It provides a way to describe various aspects of a system, such as its components, data structures, APIs, and the interactions between different components. Because Sysl files are structured, they are extremely versatile and can even be used to build a 3D-view of your application components (Figure 1 is an example of this). You can read more about Sysl here and feel free to contribute to our public Github repository.
In essence, Sysl has empowered us to build a single source of truth for APIs and present this information in various formats to our end users. One of these formats is a static web site but we are also working on building an integration (plugin) with Spotify’s open-source product, Backstage.
By leveraging the features of Sysl and Backstage we are actively enhancing our API repository and strengthening our ability to provide comprehensive and up-to-date API information to our teams. (We’ve also been able to facilitate streamlined development workflows and enable seamless integration across our engineering processes.)
It is well known that APIs are integral to modern application architecture. And while most organisations agree that consistent API implementation and protection is essential to ensuring the secure and reliable operation of their systems, we believe that thorough documentation and centralised API information management is also non-negotiable.
Kon Akopov is an Engineering Capability Lead at ANZ, where he has been employed since 2005, serving in his current role for the past three years. With a specialization in software development and a strong infrastructure background, Kon is dedicated to streamlining engineering processes, tools, and platforms for increased efficiency and effectiveness. He enjoys diving deep into engineering challenges, seeking solutions that benefit not only individual teams but the bank as a whole. Kon's approach involves breaking down complex problems into manageable targets, with a current focus on API standards and security within his team.
This article contains general information only – it does not take into account your personal needs, financial circumstances and objectives, it does not constitute any offer or inducement to acquire products and services or is not an endorsement of any products and services. Any opinions or views expressed in the article may not necessarily be the opinions or views of the ANZ Group, and to the maximum extent permitted by law, the ANZ Group makes no representation and gives no warranty as to the accuracy, currency or completeness of any information contained.