Support blackout tests

documentation/api/introduction.rst

@@ -107,6 +107,11 @@ which gives a response like this if the credentials are correct:
 Deprecation and sunset
 ----------------------
 
+Some sunsetting options are available for FlexMeasures hosts. See :ref:`api_deprecation_hosts`.
+
+FlexMeasures clients
+^^^^^^^^^^^^^^^^^^^^
+
 Professional API users should monitor API responses for the ``"Deprecation"`` and ``"Sunset"`` response headers [see `draft-ietf-httpapi-deprecation-header-02 <https://datatracker.ietf.org/doc/draft-ietf-httpapi-deprecation-header/>`_ and `RFC 8594 <https://www.rfc-editor.org/rfc/rfc8594>`_, respectively], so system administrators can be warned when using API endpoints that are flagged for deprecation and/or are likely to become unresponsive in the future.
 
 The deprecation header field shows an `IMF-fixdate <https://www.rfc-editor.org/rfc/rfc7231#section-7.1.1.1>`_ indicating when the API endpoint was deprecated.
@@ -139,3 +144,19 @@ Here is a client-side code example in Python (this merely prints out the depreca
                 print(f"Your request to {url} returned a sunset warning. Sunset: {content}")
             elif header == "Link" and ('rel="deprecation";' in content or 'rel="sunset";' in content):
                 print(f"Further info is available: {content}")
+
+.. _api_deprecation_hosts:
+
+FlexMeasures hosts
+^^^^^^^^^^^^^^^^^^
+
+When upgrading to a FlexMeasures version that sunsets an API version, clients will receive ``HTTP status 410 (Gone)`` responses when calling corresponding endpoints.
+After upgrading to one of the next FlexMeasures versions, they will receive ``HTTP status 404 (Not Found)`` responses.
+
+Hosts should not expect every client to monitor response headers and proactively upgrade to newer API versions.
+Please make sure that your users have upgraded before you upgrade to a FlexMeasures version that sunsets an API version.
+You can do this by checking your server logs for warnings about users who are still calling deprecated endpoints.
+
+In case you have users that haven't upgraded yet, and would still like to upgrade FlexMeasures, you can.
+Just set the config setting ``FLEXMEASURES_API_SUNSET_ACTIVE = False`` and consider announcing some blackout tests to your users, during which you can set this setting to ``True`` to activate the sunset.
+During such a blackout test, clients will receive ``HTTP status 410 (Gone)`` responses when calling corresponding endpoints.

documentation/changelog.rst

@@ -7,6 +7,7 @@ v0.13.0 | April XX, 2023
 ============================
 
 .. warning:: Sunset notice for API versions 1.0, 1.1, 1.2, 1.3 and 2.0: after upgrading to ``flexmeasures==0.13``, users of these API versions may receive ``HTTP status 410 (Gone)`` responses.
+             See the `documentation for deprecation and sunset <https://flexmeasures.readthedocs.io/en/latest/api/introduction.html#deprecation-and-sunset>`_.
              The relevant endpoints have been deprecated since ``flexmeasures==0.12``.
 
 .. warning:: The API endpoint (`[POST] /sensors/(id)/schedules/trigger <api/v3_0.html#post--api-v3_0-sensors-(id)-schedules-trigger>`_) to make new schedules sunsets the deprecated (since v0.12) storage flexibility parameters (they move to the ``flex-model`` parameter group), as well as the parameters describing other sensors (they move to ``flex-context``).
@@ -29,6 +30,7 @@ Bugfixes
 
 Infrastructure / Support
 ----------------------
+* Support blackout tests for sunset API versions [see `PR #651 <https://www.github.com/FlexMeasures/flexmeasures/pull/651>`_]
 * Sunset API versions 1.0, 1.1, 1.2, 1.3 and 2.0 [see `PR #650 <https://www.github.com/FlexMeasures/flexmeasures/pull/650>`_]
 * Sunset several API fields for `/sensors/<id>/schedules/trigger` (POST) that have moved into the ``flex-model`` or ``flex-context`` fields [see `PR #580 <https://www.github.com/FlexMeasures/flexmeasures/pull/580>`_]
 * Fix broken `make show-data-model` command [see `PR #638 <https://www.github.com/FlexMeasures/flexmeasures/pull/638>`_]

documentation/configuration.rst

@@ -596,24 +596,24 @@ Default: ``None``
 Sunset
 ------
 
-FLEXMEASURES_API_1_AND_2_SUNSET_ACTIVE
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+FLEXMEASURES_API_SUNSET_ACTIVE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Allow control over the effect of sunsetting API versions 1.0, 1.1, 1.2, 1.3 and 2.0.
-Specifically, if True, the endpoints in these versions will return 410 (Gone) status codes.
+Allow control over the effect of sunsetting API versions.
+Specifically, if True, the endpoints in sunset versions will return ``HTTP status 410 (Gone)`` status codes.
 If False, the endpoints will work like before, including Deprecation and Sunset headers in their response.
 
 Default: ``True``
 
-FLEXMEASURES_API_1_AND_2_SUNSET_DATE
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+FLEXMEASURES_API_SUNSET_DATE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Allow to override the default sunset date for your clients.
 
 Default: ``None`` (defaults are set internally for each sunset API version, e.g. ``"2023-05-01"`` for version 2.0)
 
-FLEXMEASURES_API_1_AND_2_SUNSET_LINK
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+FLEXMEASURES_API_SUNSET_LINK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Allow to override the default sunset link for your clients.
 

flexmeasures/api/common/utils/deprecation_utils.py

@@ -22,10 +22,10 @@ def let_host_switch_to_returning_410():
 
         # Override with custom info link, if set by host
         _sunset_info_link = current_app.config.get(
-            "FLEXMEASURES_API_1_AND_2_SUNSET_LINK", sunset_info_link
+            "FLEXMEASURES_API_SUNSET_LINK", sunset_info_link
         )
 
-        if current_app.config["FLEXMEASURES_API_1_AND_2_SUNSET_ACTIVE"]:
+        if current_app.config["FLEXMEASURES_API_SUNSET_ACTIVE"]:
             abort(
                 410,
                 f"API version {api_version_sunset} has been sunset. Please upgrade to API version {api_version_upgrade_to}. See {_sunset_info_link} for more information.",
@@ -94,12 +94,12 @@ def _after_request_handler(response: Response) -> Response:
 
             # Override sunset date if host used corresponding config setting
             _sunset = _format_sunset(
-                current_app.config.get("FLEXMEASURES_API_1_AND_2_SUNSET_DATE", sunset)
+                current_app.config.get("FLEXMEASURES_API_SUNSET_DATE", sunset)
             )
 
             # Override sunset link if host used corresponding config setting
             _sunset_link = current_app.config.get(
-                "FLEXMEASURES_API_1_AND_2_SUNSET_LINK", sunset_link
+                "FLEXMEASURES_API_SUNSET_LINK", sunset_link
             )
 
             return _add_headers(
@@ -158,12 +158,12 @@ def _after_request_handler(response: Response) -> Response:
 
         # Override sunset date if host used corresponding config setting
         _sunset = _format_sunset(
-            current_app.config.get("FLEXMEASURES_API_1_AND_2_SUNSET_DATE", sunset)
+            current_app.config.get("FLEXMEASURES_API_SUNSET_DATE", sunset)
         )
 
         # Override sunset link if host used corresponding config setting
         _sunset_link = current_app.config.get(
-            "FLEXMEASURES_API_1_AND_2_SUNSET_LINK", sunset_link
+            "FLEXMEASURES_API_SUNSET_LINK", sunset_link
         )
 
         return _add_headers(

flexmeasures/utils/config_defaults.py

@@ -131,9 +131,9 @@ class Config(object):
     )
 
     # Custom sunset switches
-    FLEXMEASURES_API_1_AND_2_SUNSET_ACTIVE: bool = True  # if True, sunset endpoints return 410 (Gone) responses; if False, they will work as before
-    FLEXMEASURES_API_1_AND_2_SUNSET_DATE: str | None = None  # e.g. 2023-05-01
-    FLEXMEASURES_API_1_AND_2_SUNSET_LINK: str | None = None  # e.g. https://flexmeasures.readthedocs.io/en/latest/api/introduction.html#deprecation-and-sunset
+    FLEXMEASURES_API_SUNSET_ACTIVE: bool = True  # if True, sunset endpoints return 410 (Gone) responses; if False, they will work as before
+    FLEXMEASURES_API_SUNSET_DATE: str | None = None  # e.g. 2023-05-01
+    FLEXMEASURES_API_SUNSET_LINK: str | None = None  # e.g. https://flexmeasures.readthedocs.io/en/latest/api/introduction.html#deprecation-and-sunset
 
 
 #  names of settings which cannot be None