Changes to Report Metadata

The list of available reports (Report List) is not guaranteed to stay the same over time, nor is a report’s metadata (Report Meta). These changes are split into non-breaking and breaking changes. The following lists examples of each.

  • Non-breaking:
    • adding a report
    • adding a dimension or metric field to a report
    • adding an entry to the values property of a field
  • Example breaking changes:
    • deprecating a report
    • removing a field
    • changing the name of a field
    • adding a field to the default_metrics array of Full Report Description.

Report Deprecation Reports may be deprecated, or superseded by another report. The Deprecation object will be present if this is the case.

When a report is past itsdeprecation_date it will no longer appear in the list of available reports. All endpoints having to do specifically with that report will return a 410 GONE response.

Report Versioning All other breaking changes to a report are tracked through the report versioning properties. Those properties are Version and Transition.

A particular version of a report may be requested using the version parameter. This parameter is just the letter v followed by the desired version. If the requested version is past its transition_date, the oldest non-transitioned version will be returned instead. If the version does not exist, then a 400 error message will be returned instead. This behavior is illustrated in the figure above.

The version parameter may be used with the Report Meta and Report Data endpoints.

Note that this version parameter should not be confused with the version in the path of the URL (/reporting/v1/std). The version in the path of the URL is the version for the reporting API itself. The version parameter is for the version of the report, and is tied to its metadata.