Migrate Chronicle API versions

Supported in:

This guide explains how to migrate your integrations to a new version of the Chronicle API. It covers endpoint updates and potential request and response differences, and provides best practices for a smooth transition.

Migrate your endpoint and requests

As the Chronicle API evolves, transitioning to newer versions ensures access to the latest features, improvements, and long-term support.

  1. Replace the existing version segment /{OLD_VERSION}/ in your endpoint paths with the new version segment /{NEW_VERSION}/.

    Example:

    Replace the existing version path with the new version path:

    • {OLD_VERSION} path:

      https://<region>-chronicle.googleapis.com/{OLD_VERSION}/
      projects/<project>/locations/<location>/instances/<instance>/...

    • {NEW_VERSION} path:

      https://<region>-chronicle.googleapis.com/{NEW_VERSION}/
      projects/<project>/locations/<location>/instances/<instance>/...

  2. Compare the API reference documentation for the specific endpoints you use and note any changes.

    1. Go to the Chronicle API REST reference: https://cloud.google.com/chronicle/docs/reference/rest

    2. For each method you use, open the API reference documentation for both the existing and new versions.

    3. Compare each method's parameters, request bodies, and response schemas.

      The new API version may structure requests and responses differently for some endpoints. Look for these potential differences:

      • Changes to field names
      • Deprecation of fields
      • Modifications to data types or formats
      • New required or optional parameters

    4. Check for field-level restrictions. The new API version may not include all the fields or features from the existing version.

    5. Update your code to the new version based on your findings.

    Example:

    When you migrate the findUdmFieldValues method, compare its documentation details for the existing version {OLD_VERSION} with the details for the new version {NEW_VERSION}.

    For example, compare the following references, where {OLD_VERSION} is v1alpha and {NEW_VERSION} is v1beta. In this case, pageSize is a deprecated field that only the v1alpha version uses:

Migration best practices

  • Test thoroughly: Before updating your production environment, test your API calls against the new version endpoints in a development or staging environment.
  • Update code: Modify your application code to handle any changes identified in the API reference comparison.
  • Monitor: After migration, monitor your applications for any unexpected behavior or errors related to the API interactions.

Need more help? Get answers from Community members and Google SecOps professionals.