One of the advantages of utilising Hava for your cloud infrastructure diagramming and documentation is the availability of a robust and flexible API.
While automatically generated diagrams, are a fantastic addition to any serious cloud development team, sometimes you might benefit from even more flexibility and automation, which is where Hava's API comes into play.
Take for instance managed service providers with thousands of cloud accounts or credentials. Connecting each individual account data source to Hava to enable the creation of diagrams and to initiate monitoring of state changes that are to be captured in version history can be an extremely lengthy and somewhat tedious task that you may want to automate.
You may also want to automate insertion of images or GIFs into your IaC build pipeline, or animate the evolution of your infrastructure from historical version history, or simply export your diagrams to your internal systems for audit purposes.
This is where Hava's API comes into play. Let's take a look at what you can do.
Sources
Automating the addition of accounts (Sources) is as simple as passing a JSON object for AWS or Azure sources or uploading GCP service account credentials.
Once your data sources have been established, either via API or the Hava SaaS or self hosted dashboard, you can then use the API to invoke a number of actions related to your data sources.
Sync
The Sync endpoint will create a job to import the resources from the nominated remote source account into Hava. The initial request returns a link to the job which can be polled to see the status of the import.
Additional metadata can be passed which will be attached to the job as well as the resources and environments created during the import. This can be useful in Build Pipelines to attach additional information such as a build number.
{
"build_no": 10,
"artifact": "new_deploy-1.0.10.tgz"
}
A typical use case for invoking a Sync via API would be creating a new set of diagrams reflecting the results of a build from within the build pipeline.
Also some Hava users automate a re-sync and export to capture all their diagrams on a daily basis.
GET
Return a list of all known data sources (Cloud accounts) connected to your Hava account.
[
{
"id": "123-3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "Sources::AWS::Key",
"info": "AKIA1234512345",
"name": "AKIA1234512345",
"display_name": "HavaRO Account",
"state": "active"
},
{
"id": "456-3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "Sources::AWS::Key",
"info": "AKIA4567845678",
"name": "AKIA4567845678",
"display_name": "HavaRO Development",
"state": "active"
}
]
Or return an individual Source
{
"id": "123-3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "Sources::AWS::Key",
"info": "AKIA1234512345",
"name": "AKIA1234512345",
"display_name": "HavaRO Account",
"state": "active"
}
Put
Update and existing source's name or credentials
using Put/Sources you can pass parameters to be updated.
{
"name": "Updated AWS Key",
"access_key": "AKIA12341234",
"secret_key": "v.co1A3/sqpdke"
}
Any properties not defined in the update will not be updated.
Once your Data Sources are established you can then start to interrogate or create custom environments (diagram sets) within your Hava account for each of your data sources.
Environments
There are a number of API calls that enable you to return specific information pertaining to an environment, such as listing all environments, listing the revisions of a specific environment or pulling back the details of a specific environment.
You can also create a new environment (diagram set) using custom queries to pull back the resources returned by the query into a new diagram set.
You may also update specific details related to a custom environment and delete the entire custom environment using the API.
Views
When you connect Hava to your cloud accounts an initial set of diagrams are created. These are referred to as "Views" within the application.
- Infrastructure View - is a logically laid out clean visualization of resources.
- Extended Infrastructure View - supplements the diagram with additional info.
- Security View (AWS and Azure )- maps out security groups and overlays open ports.
- List View - provides a detailed list of all visualized and non visualized resources.
- Container View - displays containerized infrastructure
The API enables you to fetch and export these views from Hava.
The view_id can be obtained from the environment model. This method will then return a link to the job endpoint which you can poll for the status of the export. Once complete it will return a link to the export file ready for download.
The available download {format} values are:
- PNG
- VDSX
- CSV
- JSON
You may also nominate whether to show connections and labels as well as choosing to export the isometric (3d) format instead of the standard topology diagram.
Resources
Hava's automated cloud diagram API allows you to retrieve a detailed list of resources that relate to the source_id or source-Id's you request.
The list of resources returned includes both the resources visualized on your diagrams and the ones that are discovered but only found on the detailed "List View", in other words, the non-visualized resources that Hava leaves off your infrastructure diagrams to keep them readable.
Jobs
Hava's API allows you to query a specific job to establish the status or view the link to the file created by the job.
The returned state will indicate if the job is still active, whether it failed or will redirect to the results of the job.
Teams
Your Hava account provides the ability build user teams to provide common account or project access. The API provides the ability to manage teams using a combination of unique team id's and email addresses.
Adding a team member via API would look something like this:
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Development",
"account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"roles": [
"Admin"
],
"members": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"username": "bob.smith",
"email": "bob.smith@company.com",
"first_name": "Bob",
"last_name": "Smith"
}
]
}
A full list of detailed schemas relating to hava's API interface including
- Views
- Teams
- Sources
- SourcesAWSKey
- SourcesAWSCAR
- SourcesAzureCredentials
- EnvironmentRevision
- EnvironmentSummary
- Environment
- Resources
- Errors
can be found via comprehensive documentation on SwaggerHub
There are almost unlimited ways you could utilise Hava's API.
- Schedule a script to export documentation daily.
- Export previous versions of your diagrams, stitch them together to produce an animation
- Script the addition of bulk accounts or sources into hava
- Export current and previous environments to JSON files and diff them to quickly identify changes in your environments
- Add API calls into your IaC Build Pipeline to add artifacts documenting the environment post-build
David Brenecki of Servian demonstrated an excellent use of the Hava API in this Medium Post earlier this year :
To take advantage of Hava's API requires a Teams plan or self-hosted solution.
You can take a 14 day free Trial of Hava at any time, or you can call and chat to our customer support team to discuss your AWS, Azure and GCP automated cloud documentation requirements or arrange a one-on-one demo.
