remove(api): Versions 1 to 2 are Gone or Not Found (#667)

Remove API versions 1.0, 1.1, 1.2, 1.3 and 2.0, while allowing hosts to switch between ``HTTP status 410 (Gone)`` and ``HTTP status 404 (Not Found)`` responses. * Unlink internal logic from API endpoints Signed-off-by: F.N. Claessen <felix@seita.nl> * Remove endpoint implementations Signed-off-by: F.N. Claessen <felix@seita.nl> * Turning off the sunset switch now starts returning 404 responses Signed-off-by: F.N. Claessen <felix@seita.nl> * changelog entries Signed-off-by: F.N. Claessen <felix@seita.nl> * typo Signed-off-by: F.N. Claessen <felix@seita.nl> * Explain deprecation stages Signed-off-by: F.N. Claessen <felix@seita.nl> --------- Signed-off-by: F.N. Claessen <felix@seita.nl>
FlexMeasures · May 8, 2023 · a746ae4 · a746ae4
1 parent 6e9c32f
commit a746ae4
Show file tree

Hide file tree

Showing 19 changed files with 152 additions and 3,642 deletions.
diff --git a/documentation/api/change_log.rst b/documentation/api/change_log.rst
@@ -112,6 +112,11 @@ v3.0-0 | 2022-03-25
     - Rewrote the sections on roles and sources into a combined section that refers to account roles rather than USEF roles.
     - Deprecated the section on group notation.
 
+v2.0-7 | 2022-05-05
+"""""""""""""""""""
+
+*API v2.0 is removed.*
+
 v2.0-6 | 2022-04-26
 """""""""""""""""""
 
@@ -163,6 +168,12 @@ v2.0-0 | 2020-11-14
 
 - Added REST endpoints for managing assets: `/assets/` (GET, POST) and `/asset/<id>` (GET, PATCH, DELETE).
 
+
+v1.3-14 | 2022-05-05
+""""""""""""""""""""
+
+*API v1.3 is removed.*
+
 v1.3-13 | 2022-04-26
 """"""""""""""""""""
 
@@ -259,6 +270,11 @@ v1.3-0 | 2020-01-28
 - The *postUdiEvent* endpoint now triggers scheduling jobs to be set up (rather than scheduling directly triggered by the *getDeviceMessage* endpoint)
 - The *getDeviceMessage* now queries the job queue and database for an available schedule
 
+v1.2-6 | 2022-05-05
+"""""""""""""""""""
+
+*API v1.2 is removed.*
+
 v1.2-5 | 2022-04-26
 """""""""""""""""""
 
@@ -315,6 +331,11 @@ v1.2-0 | 2018-09-08
 - Added a description of the *postUdiEvent* endpoint in the Prosumer and Simulation sections
 - Added a description of the *getDeviceMessage* endpoint in the Prosumer and Simulation sections
 
+v1.1-8 | 2022-05-05
+"""""""""""""""""""
+
+*API v1.1 is removed.*
+
 v1.1-7 | 2022-04-26
 """""""""""""""""""
 
@@ -378,6 +399,11 @@ v1.1-0 | 2018-07-15
 
 - Added a description of the *getPrognosis* endpoint in the Supplier section
 
+v1.0-4 | 2022-05-05
+"""""""""""""""""""
+
+*API v1.0 is removed.*
+
 v1.0-3 | 2022-04-26
 """""""""""""""""""
 

diff --git a/documentation/api/introduction.rst b/documentation/api/introduction.rst
@@ -100,17 +100,19 @@ which gives a response like this if the credentials are correct:
         "user_id": "<ID of the user>"
     }
 
-.. note:: Each access token has a limited lifetime, see :ref:`auth`.
+.. note:: Each access token has a limited lifetime, see :ref:`api_auth`.
 
 .. _api_deprecation:
 
 Deprecation and sunset
 ----------------------
 
-Some sunsetting options are available for FlexMeasures hosts. See :ref:`api_deprecation_hosts`.
+When an API feature becomes obsolete, we deprecate it.
+Deprecation of major features doesn't happen a lot, but when it does, it happens in multiple stages, during which we support clients and hosts in adapting.
+For more information on our multi-stage deprecation approach and available options for FlexMeasures hosts, see :ref:`Deprecation and sunset for hosts<api_deprecation_hosts>`.
 
-FlexMeasures clients
-^^^^^^^^^^^^^^^^^^^^
+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.
 
@@ -147,11 +149,24 @@ Here is a client-side code example in Python (this merely prints out the depreca
 
 .. _api_deprecation_hosts:
 
-FlexMeasures hosts
-^^^^^^^^^^^^^^^^^^
+Hosts
+^^^^^
 
-When upgrading to a FlexMeasures version that sunsets an API version (e.g. ``flexmeasures==0.13.0`` sunsets API version 2), clients will receive ``HTTP status 410 (Gone)`` responses when calling corresponding endpoints.
-After upgrading to one of the next FlexMeasures versions (e.g. ``flexmeasures==0.14.0``), they will receive ``HTTP status 404 (Not Found)`` responses.
+FlexMeasures versions go through the following stages for deprecating major features (such as API versions):
+
+- :ref:`api_deprecation_stage_1`: status 200 (OK) with relevant headers, plus a toggle to 410 (Gone) for blackout tests
+- :ref:`api_deprecation_stage_2`: status 410 (Gone), plus a toggle to 200 (OK) for sunset rollbacks
+- :ref:`api_deprecation_stage_3`: status 404 (Not Found), plus a toggle to 410 (Gone) for removal rollbacks
+- :ref:`api_deprecation_stage_4`: status 404 (Not Found), and removal of relevant endpoints
+
+Let's go over these stages in more detail.
+
+.. _api_deprecation_stage_1:
+
+Stage 1: Deprecation
+""""""""""""""""""""
+
+When upgrading to a FlexMeasures version that deprecates an API version (e.g. ``flexmeasures==0.12`` deprecates API version 2), clients will receive ``"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].
 
 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.
@@ -171,6 +186,31 @@ During such a blackout test, clients will receive ``HTTP status 410 (Gone)`` res
    The test is meant to help developers understand the impact the retirement will have on the applications and users.
    `Source: Platform of Trust <https://design.oftrust.net/api-migration-policies/blackout-testing>`_
 
+.. _api_deprecation_stage_2:
+
+Stage 2: Preliminary sunset
+"""""""""""""""""""""""""""
+
+When upgrading to a FlexMeasures version that sunsets an API version (e.g. ``flexmeasures==0.13`` sunsets API version 2), clients will receive ``HTTP status 410 (Gone)`` responses when calling corresponding endpoints.
+
 In case you have users that haven't upgraded yet, and would still like to upgrade FlexMeasures (to the version that officially sunsets the API version), you can.
-For a little while after sunset (usually one more minor version), we will continue to support "letting the sun unset".
-To enable this, just set the config setting ``FLEXMEASURES_API_SUNSET_ACTIVE = False`` and consider announcing some more blackout tests to your users, during which you can set this setting to ``True`` to activate the sunset.
+For a little while after sunset (usually one more minor version), we will continue to support a "sunset rollback".
+To enable this, just set the config setting ``FLEXMEASURES_API_SUNSET_ACTIVE = False`` and consider announcing some more blackout tests to your users, during which you can set this setting to ``True`` to reactivate the sunset.
+
+.. _api_deprecation_stage_3:
+
+Stage 3: Definitive sunset
+""""""""""""""""""""""""""
+
+After upgrading to one of the next FlexMeasures versions (e.g. ``flexmeasures==0.14``), clients that call sunset endpoints will receive ``HTTP status 404 (Not Found)`` responses.
+In case you need clients to receive the slightly more informative ``HTTP status 410 (Gone)``  for a little while longer, we will continue to support a "removal rollback".
+To enable this, just set the config setting ``FLEXMEASURES_API_SUNSET_ACTIVE = True``.
+This, just like in deprecation stages 1 and 2, leads to status 410 (Gone) responses.
+Note that ``FLEXMEASURES_API_SUNSET_ACTIVE = False`` now leads to status 404 (Not Found) responses, unlike in deprecation stages 1 and 2, where this would have lead to status 200 (OK) responses.
+
+.. _api_deprecation_stage_4:
+
+Stage 4: Removal
+""""""""""""""""
+
+After upgrading to one of the next FlexMeasures versions (e.g. ``flexmeasures==0.15``), clients that call sunset endpoints will receive ``HTTP status 404 (Not Found)`` responses.
diff --git a/documentation/changelog.rst b/documentation/changelog.rst
@@ -16,6 +16,7 @@ Infrastructure / Support
 ----------------------
 
 * The setting FLEXMEASURES_PLUGINS can be set as environment variable now (as a comma-separated list) [see `PR #660 <https://www.github.com/FlexMeasures/flexmeasures/pull/660>`_]
+* Remove API versions 1.0, 1.1, 1.2, 1.3 and 2.0, while allowing hosts to switch between ``HTTP status 410 (Gone)`` and ``HTTP status 404 (Not Found)`` responses [see `PR #667 <https://www.github.com/FlexMeasures/flexmeasures/pull/667>`_]
 
 .. warning:: The setting `FLEXMEASURES_PLUGIN_PATHS` has been deprecated since v0.7. It has now been sunset. Please replace it with :ref:`plugin-config`.
 

diff --git a/documentation/configuration.rst b/documentation/configuration.rst
@@ -618,10 +618,10 @@ FLEXMEASURES_API_SUNSET_ACTIVE
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 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.
+Specifically, if True, the endpoints of sunset API versions will return ``HTTP status 410 (Gone)`` status codes.
+If False, these endpoints will either return ``HTTP status 404 (Not Found) status codes``, or work like before (including Deprecation and Sunset headers in their response), depending on whether the installed FlexMeasures version still contains the endpoint implementations.
 
-Default: ``True``
+Default: ``False``
 
 FLEXMEASURES_API_SUNSET_DATE
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/flexmeasures/api/common/utils/deprecation_utils.py b/flexmeasures/api/common/utils/deprecation_utils.py
@@ -14,10 +14,16 @@ def sunset_blueprint(
     api_version_sunset: str,
     sunset_link: str,
     api_version_upgrade_to: str = "3.0",
+    blueprint_contents_removed: bool = True,
 ):
-    """Sunsets every route on a blueprint by returning 410 (Gone) responses.
+    """Sunsets every route on a blueprint by returning 410 (Gone) responses, if sunset is active.
 
-    Such errors will be logged by utils.error_utils.error_handling_router.
+    Whether the sunset is active can be toggled using the config setting "FLEXMEASURES_API_SUNSET_ACTIVE".
+    If inactive, either:
+    - return 404 (Not Found) if the blueprint contents have been removed, or
+    - pass the request to be handled by the endpoint implementation.
+
+    Errors will be logged by utils.error_utils.error_handling_router.
     """
 
     def let_host_switch_to_returning_410():
@@ -30,6 +36,12 @@ def let_host_switch_to_returning_410():
                 410,
                 f"API version {api_version_sunset} has been sunset. Please upgrade to API version {api_version_upgrade_to}. See {_sunset_link} for more information.",
             )
+        elif blueprint_contents_removed:
+            abort(404)
+        else:
+            # Sunset is inactive and blueprint contents are still there,
+            # so we let the request pass to the endpoint implementation
+            pass
 
     blueprint.before_request(let_host_switch_to_returning_410)