Add section 11.7 about COUNTER API extensions and the Month_Details extension description (#331)

source/11-extending/07-api-extensions-for-the-counter-api.rst

@@ -0,0 +1,61 @@
+.. The COUNTER Code of Practice © 2017-2026 by COUNTER Metrics
+   is licensed under CC BY 4.0. To view a copy of this license,
+   visit https://creativecommons.org/licenses/by/4.0/
+
+.. _api-extensions:
+
+Extensions for the COUNTER API
+-------------------------------
+
+In addition to the extensions that can be included in COUNTER Reports (see :numref:`reserved-elements`), COUNTER recognizes that report providers may want to extend the COUNTER API to provide additional information to report consumers. This section describes OPTIONAL API extensions that can be included in COUNTER API responses.
+
+Requesting API Extensions
+"""""""""""""""""""""""""
+
+API extensions are requested using an ``include_{element name in lower case}`` parameter with permissible values ``False`` (default) and ``True``. This follows the same pattern as the ``include_parent_details`` and ``include_component_details`` report attributes (see :numref:`filters-attributes`).
+
+Support for API extensions is OPTIONAL. If a report provider does not support an extension, the response SHOULD be the same as when the parameter is omitted or set to ``False``. Report providers that do not support an extension are not expected to implement any special way of signaling that the extension is not supported.
+
+When an extension is supported, the information SHOULD be customer specific where possible. For example, the date on which data for a month last changed may depend on the customer ID and other credentials used in the request.
+
+When information for an extension is not available, the corresponding element MUST be omitted rather than included with an empty or placeholder value.
+
+Month_Details Extension
+"""""""""""""""""""""""
+
+The Month_Details extension allows report providers to signal to report consumers when data for a report has changed and may need reharvesting. Because the date of change may be report specific and may depend on the credentials used in the request, this information is provided in the response for the ``/r51/reports`` COUNTER API path (see :numref:`api-paths`), which MUST be protected by the methods described in :numref:`api-security`.
+
+The extension is requested using the ``include_month_details`` parameter with permissible values ``False`` (default) and ``True``.
+
+When ``include_month_details=True``, each report in the response MAY include a ``Month_Details`` element. The ``Month_Details`` element is an object whose keys are months in ``yyyy-mm`` format. Each month key maps to an object that contains information about that month. The elements defined for each month are ``Last_Change_Date`` and, optionally, ``Last_Change_Note``. The structure is extensible so that additional per-month elements can be defined in the future. Report consumers MUST ignore elements in ``Month_Details`` that they do not recognize.
+
+The required ``Last_Change_Date`` element gives the date and time when the data for that month last changed, in RFC3339 date-time format (*yyyy-mm-ddThh:mm:ssZ*). Report providers MUST include a month in ``Month_Details`` only when ``Last_Change_Date`` information is available for that month. Months for which the information is not available MUST be omitted. If no months have ``Last_Change_Date`` information for a report, the ``Month_Details`` element MUST be omitted for that report.
+
+The optional ``Last_Change_Note`` element allows the report provider to include information about why the data for that month has changed.
+
+An example of a report entry in the response for ``/r51/reports`` with the Month_Details extension is:
+
+.. code-block:: JSON
+
+   {
+     "Report_Name": "Platform Report",
+     "Report_ID": "PR",
+     "Release": "5.1",
+     "Report_Description": "A customizable report summarizing activity across a report provider’s platforms that allows the user to apply filters and select other configuration options.",
+     "First_Month_Available": "2024-01",
+     "Last_Month_Available": "2026-03",
+     "Month_Details": {
+       "2026-03": {
+         "Last_Change_Date": "2026-04-18T20:30:40Z",
+         "Last_Change_Note": "Data restated after correction of duplicate request counts."
+       },
+       "2026-02": {
+         "Last_Change_Date": "2026-03-29T01:02:03Z"
+       }
+     }
+   }
+
+
+The ``Month_Details`` element MAY be included for some reports in the response and omitted for others. Report consumers can compare the ``Last_Change_Date`` value for a month with the date and time when they last harvested usage data for that report and month to determine whether reharvesting is needed.
+
+No particular order is required for the month keys in ``Month_Details`` but descending chronological order is RECOMMENDED. Each month key MUST be within the range from ``First_Month_Available`` to ``Last_Month_Available`` inclusive for that report.

source/11-extending/index.rst

@@ -18,3 +18,4 @@ COUNTER recognises that some report providers may want to provide customized ver
    04-creating-new-values-for-enumerated-elements-and-attributes
    05-reserved-values-available-for-extending-reports
    06-restrictions-in-using-customized-elements-and-values
+   07-api-extensions-for-the-counter-api