Data Retention Policy REST API

By making an HTTP GET request to the following URL relative to IQ Server's base URL the data retention policies for a given organization can be retrieved:

GET /api/v2/dataRetentionPolicies/organizations/{organizationId}

You use the Organizations REST API to locate the organizationId for an organization.

Assuming a local installation of IQ Server with its default configuration, the following example using the cURL tool queries the retention policies for the root organization:

curl -u admin:admin123 http://localhost:8070/api/v2/dataRetentionPolicies/organizations/ROOT_ORGANIZATION_ID

Again, assuming the default configuration, the above request would yield this JSON response payload (formatted here for readability):

{
  "applicationReports": {
    "stages": {
      "develop": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "3 months"
      },
      "build": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "3 months"
      },
      "stage-release": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "3 months"
      },
      "release": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "10 years"
      },
      "operate": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "10 years"
      },
      "continuous-monitoring": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "3 months"
      }
    }
  },
  "successMetrics": {
    "inheritPolicy": false,
    "enablePurging": true,
    "maxAge": "1 year"
  },
  "containerReports": {
    "inheritPolicy": false,
    "enablePurging": true,
    "maxAge": "3 months"
  }  
}

For application reports, each stage in the application lifecycle (develop, build, etc.) has its own retention policy. A notable exception are application reports that were created by continuous monitoring: They are not subject to the retention policy of whatever stage is being monitored but have their own retention policy under the key continuous-monitoring.

Note that the response lists only those stages that the installed product license enables. So you might see fewer entries with your IQ Server than shown in the above example.

A single retention policy for the application reports consists of these fields:

The retention policy for container reports is returned under the top-level containerReports key. It uses the same inheritPolicy, enablePurging, maxAge, and maxCount fields as an application report retention policy. The latest container report for each application is retained. The containerReports key is included when the Data Retention feature is licensed and container image evaluation is licensed and enabled.

The retention policy for Success Metrics consists mostly of the same fields as those for application reports:

A HTTP PUT request to the same URL when reading the current configuration is used to change the retention policies:

PUT /api/v2/dataRetentionPolicies/organizations/{organizationId}

The request needs to be accompanied by a JSON payload that has generally the same format as described above. You can omit all but one stage from the stages map to update selected application report policies. You can also specify only successMetrics or containerReports to update that policy without changing the other retention policies.

The next example would update the retention policy of the root organization regarding application reports for the build stage:

curl -u admin:admin123 -H "Content-Type: application/json" -X PUT -d '{"applicationReports": {"stages": {"build": {"enablePurging": true, "maxAge": "2 weeks", "maxCount": 100}}}}' http://localhost:8070/api/v2/dataRetentionPolicies/organizations/ROOT_ORGANIZATION_ID

The following example enables container report purging and retains reports for up to three months or until the report count exceeds 100:

curl -u admin:admin123 -H "Content-Type: application/json" -X PUT -d '{"containerReports": {"enablePurging": true, "maxAge": "3 months", "maxCount": 100}}' http://localhost:8070/api/v2/dataRetentionPolicies/organizations/ROOT_ORGANIZATION_ID

Note that when enablePurging is true, at least one purge criteria, maxAge or maxCount, needs to be specified.

If the request body is malformed, no changes to the retention policies are carried out and the status code 400 ("Bad Request") is sent back.

To optimize resource usage for this REST API, IQ Server has a preset limit of purging 5000 reports in one call. If your reports to be purged exceed 5000, and were not purged before, you will have to issue multiple calls to this REST API, to reduce the reports below or equal to the maxCount field setting.

IQ Server will automatically apply the maxCount field setting for subsequent purges.