Migrating to New API Versions
BigPanda is constantly improving our APIs for better functionality, reliability, and usability. While most of our updates are seamless and require no changes, occasionally a whole new API version is necessary.
If you were using the older version, migrating to a V2 API only takes a few simple steps:
Update the call base URL.
Validate the Authentication Type - All new APIs require authentication through User API Key. If your previous APIs was leveraging the Org Token, you'll need to issue and update new credentials.
Validate body fields or values - While we strive to keep payloads consistent, sometimes a change is necessary to make space for new or improved functionality. Always review payloads to ensure they match new parameters.
(Optional) Set pagination or filter rules - Some GET calls now have pagination or filtering enabled to improve readability, response times, and reliability. For large data sets, you may need to configure filters or pagination, and scripted recurring calls to retrieve all data.
Test the API - As when making any changes to your BigPanda configuration, we recommend sending sample API calls to test the changes.
Migrating existing workflows to Alert Enrichment 2.1
The Alert Enrichments V2.1 API allows you to programmatically create custom tags and enrichment items that add contextual information to alerts. It supports the mapping enrichment technique, which creates alert custom tags by looking up values in a data mapping table.
Use the Alert Enrichment V2.1 API to define alert tags and enrichment maps to add vital context to ongoing alerts.
Read more about how alerts are contextualized and the potential correlation and automation possibilities of alert enrichment in the Alert Intelligence documentation.
Mandatory migration
All customers will need to move to the V2.1 API. The Enrichment V1 and V2.0 API will be deprecated in the future.
API Improvements
Improved composition and extraction enrichment item functionality and features
Alert tags can now be duplicated, marked inactive, and have a description
Mapping tables now automatically enrich existing alert tags
Mapping enrichment items can be reordered on a per-tag basis
Enabling future audit-log functionality
Bulk operations now available for enrichment items
In order to leverage these improved capabilities, your organization will need to migrate your analytics into the new tool and data set.
Preparing for migration
Migrating to the Alert Enrichment V2.1 API is a simple, seamless process. **During the initial migration phase**, you will have access to the V2.0 API as well as the new V2.1.
Before beginning migration, review all manual and automated processes that leverage the existing Alert Enrichment APIs. This includes any mapping enrichment APIs leveraging the V1.0 and V2.0 Enrichment API.
Simple migration
If you are only using the Alert Enrichment V1 API to manage mapping enrichments, the migration process will require only a few steps:
1. Change the endpoint name attached to Mapping Enrichment calls to the new `/v2.1/mapping-enrichment/` endpoint
2. Validate payload format matches the new requirements
3. Test an enrichment map to ensure it is uploading correctly
4. (Optional) If choosing to implement API management of composition and extraction tags, use the new V2.1 endpoints and JSON payload formats.
Complex migration
If you are using the Enrichment V2.0 API to manage composition and extraction enrichments, the migration process will require a few additional updates:
1. Change the endpoint name attached to all enrichment calls to the new endpoints:
/v2.0/alert-enrichments (mapping type) --> /v2.1/mapping-enrichment
/v2.0/alert-enrichments (non-mapping type) --> /v2.1/enrichments-config/tags/<TAG_NAME>/enrichments
2. Validate payload format matches the new requirements
The object payload for Tag Rules or Enrichment Items is changing from a single object to an array of objects. Composition and extraction enrichments will be nested within the enrichment array.
curl Enrichment Items Array Format{
"name": "tag_name",
"active": true,
"description": "",
"enrichments": [
{
"type": "extraction",
"active": true,
"when": {},
"config": {
"source": "host",
"destination": "tag_name",
"regex": "(.*)",
"template": null
},
"note": null
},
{
"type": "composition",
"active": true,
"when": {},
"config": {
"destination": "tag_name",
"value": "val-${host6666}"
},
"note": "wiki.com"
}
]
}
3. Test each enrichment and call type to ensure it is functioning correctlyThe [Alert Enrichments V2.1 API](https://docs.bigpanda.io/reference/alert-enrichment-v2-1-api) allows you to programmatically create custom tags and enrichment items that add contextual information to alerts. It supports the mapping enrichment technique, which creates alert custom tags by looking up values in a data mapping table.