.. _api_change_log:

API change log
===============

.. note:: The FlexMeasures API follows its own versioning scheme. This is also reflected in the URL, allowing developers to upgrade at their own pace.


v3.0-1 | 2022-05-08
"""""""""""""""""""

- Added REST endpoint for checking application health (readiness to accept requests): `/health/ready` (GET).


v3.0-0 | 2022-03-25
"""""""""""""""""""

- Added REST endpoint for listing sensors: `/sensors` (GET).
- Added REST endpoints for managing sensor data: `/sensors/data` (GET, POST).
- Added REST endpoints for managing assets: `/assets` (GET, POST) and `/assets/<id>` (GET, PATCH, DELETE).
- Added REST endpoints for triggering and getting schedules: `/sensors/<id>/schedules/<uuid>` (GET) and `/sensors/<id>/schedules/trigger` (POST).
- [**Breaking change**] Switched to plural resource names for REST endpoints:  `/users/<id>` (GET, PATCH) and `/users/<id>/password-reset` (PATCH).
- [**Breaking change**] Deprecated the following endpoints (NB replacement endpoints mentioned below no longer require the message "type" field):

    - *getConnection* -> use `/sensors` (GET) instead
    - *getDeviceMessage* -> use `/sensors/<id>/schedules/<uuid>` (GET) instead, where <id> is the sensor id from the "event" field and <uuid> is the value of the "schedule" field returned by `/sensors/<id>/schedules/trigger` (POST)
    - *getMeterData* -> use `/sensors/data` (GET) instead, replacing the "connection" field with "sensor"
    - *getPrognosis* -> use `/sensors/data` (GET) instead, replacing the "connection" field with "sensor"
    - *getService* -> consult the public API documentation instead, at https://flexmeasures.readthedocs.io
    - *postMeterData* -> use `/sensors/data` (POST) instead, replacing the "connection" field with "sensor"
    - *postPriceData* -> use `/sensors/data` (POST) instead, replacing the "market" field with "sensor"
    - *postPrognosis* -> use `/sensors/data` (POST) instead, replacing the "connection" field with "sensor"
    - *postUdiEvent* -> use `/sensors/<id>/schedules/trigger` (POST) instead, where <id> is the sensor id from the "event" field, and rename the following fields:

        - "datetime" -> "start"
        - "value -> "soc-at-start"
        - "unit" -> "soc-unit"
        - "targets" -> "soc-targets"
        - "soc_min" -> soc-min"
        - "soc_max" -> soc-max"
        - "roundtrip_efficiency" -> "roundtrip-efficiency"

    - *postWeatherData* -> use `/sensors/data` (POST) instead
    - *restoreData*

- Changed the Introduction section:

    - Rewrote the section on service listing for API versions to refer to the public documentation.
    - Rewrote the section on entity addresses to refer to *sensors* instead of *connections*.
    - 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-4 | 2022-01-04
"""""""""""""""""""

- Updated entity addresses in documentation, according to the fm1 scheme.
- Changed the Introduction section:

    - Rewrote the subsection on entity addresses to refer users to where they can find the entity addresses of their sensors.
    - Rewrote the subsection on sensor identification (formerly known as asset identification) to place the fm1 scheme front and center.

- Fixed the categorisation of the *postMeterData*, *postPrognosis*, *postPriceData* and *postWeatherData* endpoints from the User category to the Data category.

v2.0-3 | 2021-06-07
"""""""""""""""""""

- Updated all entity addresses in documentation according to the fm0 scheme, preserving backwards compatibility.
- Introduced the fm1 scheme for entity addresses for connections, markets, weather sensors and sensors.



v2.0-2 | 2021-04-02
"""""""""""""""""""

- [**Breaking change**] Switched the interpretation of horizons to rolling horizons.
- [**Breaking change**] Deprecated the use of ISO 8601 repeating time intervals to denote rolling horizons.
- Introduced the "prior" field for *postMeterData*, *postPrognosis*, *postPriceData* and *postWeatherData* endpoints.
- Changed the Introduction section:

    - Rewrote the subsection on prognoses to explain the horizon and prior fields.

- Changed the Simulation section:

    - Rewrote relevant examples using horizon and prior fields.

v2.0-1 | 2021-02-19
"""""""""""""""""""

- Added REST endpoints for managing users: `/users/` (GET), `/user/<id>` (GET, PATCH) and `/user/<id>/password-reset` (PATCH).

v2.0-0 | 2020-11-14
"""""""""""""""""""

- Added REST endpoints for managing assets: `/assets/` (GET, POST) and `/asset/<id>` (GET, PATCH, DELETE).


v1.3-11 | 2022-01-05
""""""""""""""""""""

*Affects all versions since v1.3*.

- Changed and extended the *postUdiEvent* endpoint:

    - The recording time of new schedules triggered by calling the endpoint is now the time at which the endpoint was called, rather than the datetime of the sent state of charge (SOC).
    - Introduced the "prior" field for the purpose of communicating an alternative recording time, thereby keeping support for simulations.
    - Introduced an optional "roundtrip_efficiency" field, for use in scheduling.

v1.3-10 | 2021-11-08
""""""""""""""""""""

*Affects all versions since v1.3*.

- Fixed the *getDeviceMessage* endpoint for cases in which there are multiple schedules available, by returning only the most recent one.

v1.3-9 | 2021-04-21
"""""""""""""""""""

*Affects all versions since v1.0*.

- Fixed regression by partially reverting the breaking change of v1.3-8: Re-instantiated automatic inference of horizons for Post requests for API versions below v2.0, but changed to inference policy: now inferring the data was recorded **right after each event** took place (leading to a zero horizon for each data point) rather than **after the last event** took place (which led to a different horizon for each data point); the latter had been the inference policy before v1.3-8.

v1.3-8 | 2020-04-02
"""""""""""""""""""

*Affects all versions since v1.0*.

- [**Breaking change**, partially reverted in v1.3-9] Deprecated the automatic inference of horizons for *postMeterData*, *postPrognosis*, *postPriceData* and *postWeatherData* endpoints for API versions below v2.0.

v1.3-7 | 2020-12-16
"""""""""""""""""""

*Affects all versions since v1.0*.

- Separated the dual purpose of the "horizon" field in the *getMeterData* and *getPrognosis* endpoints by introducing the "prior" field:

    - The "horizon" field in GET endpoints is now always interpreted as a rolling horizon, regardless of whether it is stated as an ISO 8601 repeating time interval.
    - The *getMeterData* and *getPrognosis* endpoints now accept an optional "prior" field to select only data recorded before a certain ISO 8601 timestamp (replacing the unintuitive usage of the horizon field for specifying a latest time of belief).

v1.3-6 | 2020-12-11
"""""""""""""""""""

*Affects all versions since v1.0*.

- The *getMeterData* and *getPrognosis* endpoints now return the INVALID_SOURCE status 400 response in case the optional "source" field is used and no relevant sources can be found.

v1.3-5 | 2020-10-29
"""""""""""""""""""

*Affects all versions since v1.0*.

- Endpoints to POST meter data will now check incoming data to see if the required asset's resolution is being used ― upsampling is done if possible.
  These endpoints can now return the REQUIRED_INFO_MISSING status 400 response.
- Endpoints to GET meter data will return data in the asset's resolution ― downsampling to the "resolution" field is done if possible.
- As they need to determine the asset, all of the mentioned POST and GET endpoints can now return the UNRECOGNIZED_ASSET status 400 response.

v1.3-4 | 2020-06-18
"""""""""""""""""""

- Improved support for use cases of the *getDeviceMessage* endpoint in which a longer duration, between posting UDI events and retrieving device messages based on those UDI events, is required; the default *time to live* of UDI event identifiers is prolonged from 500 seconds to 7 days, and can be set as a config variable (`FLEXMEASURES_PLANNING_TTL`)

v1.3-3 | 2020-06-07
"""""""""""""""""""

- Changed backend support (API specifications unaffected) for scheduling charging stations to scheduling Electric Vehicle Supply Equipment (EVSE), in accordance with the Open Charge Point Interface (OCPI).

v1.3-2 | 2020-03-11
"""""""""""""""""""

- Fixed example entity addresses in simulation section


v1.3-1 | 2020-02-08
"""""""""""""""""""

- Backend change: the default planning horizon can now be set in FlexMeasures's configuration (`FLEXMEASURES_PLANNING_HORIZON`)

v1.3-0 | 2020-01-28
"""""""""""""""""""

- Introduced new event type "soc-with-targets" to support scheduling charging stations (see extra example for the *postUdiEvent* endpoint)
- 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-3 | 2020-01-28
"""""""""""""""""""

- Updated endpoint descriptions with additional possible status 400 responses:

    - INVALID_DOMAIN for invalid entity addresses
    - UNKNOWN_PRICES for infeasible schedules due to missing prices

v1.2-2 | 2018-10-08
"""""""""""""""""""

- Added a list of registered types of weather sensors to the Simulation section and *postWeatherData* endpoint
- Changed example for the *postPriceData* endpoint to reflect Korean situation

v1.2-1 | 2018-09-24
"""""""""""""""""""

- Added a local table of contents to the Simulation section
- Added a description of the *postPriceData* endpoint in the Simulation section
- Added a description of the *postWeatherData* endpoint in the Simulation section
- Revised the subsection about posting power data in the Simulation section
- Revised the entity address for UDI events to include the type of the event

.. code-block:: json

    i.e.

    {
        "type": "PostUdiEventRequest",
        "event": "ea1.2021-01.io.flexmeasures.company:7:10:203:soc",
    }

    rather than the erroneously double-keyed:

    {
        "type": "PostUdiEventRequest",
        "event": "ea1.2021-01.io.flexmeasures.company:7:10:203",
        "type": "soc"
    }

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-5 | 2020-06-18
"""""""""""""""""""

- Fixed the *getConnection* endpoint where the returned list of connection names had been unnecessarily nested

v1.1-4 | 2020-03-11
"""""""""""""""""""

- Added support for posting daily and weekly prices for the *postPriceData* endpoint

v1.1-3 | 2018-09-08
"""""""""""""""""""

- Added the Simulation section:

    - Added information about setting up a new simulation
    - Added examples for calling the *postMeterData* endpoint
    - Added example for calling the *getPrognosis* endpoint

v1.1-2 | 2018-08-15
"""""""""""""""""""

- Added the *postPrognosis* endpoint
- Added the *postPriceData* endpoint
- Added a description of the *postPrognosis* endpoint in the Aggregator section
- Added a description of the *postPriceData* endpoint in the Aggregator and Supplier sections
- Added the *restoreData* endpoint for servers in play mode

v1.1-1 | 2018-08-06
"""""""""""""""""""

- Added the *getConnection* endpoint
- Added the *postWeatherData* endpoint
- Changed the Introduction section:

    - Added information about the sign of power values (production is negative)
    - Updated information about horizons (now anchored to the end of each time interval rather than to the start)
 
- Added an optional horizon to the *postMeterData* endpoint

v1.1-0 | 2018-07-15
"""""""""""""""""""

- Added the *getPrognosis* endpoint
- Changed the *getMeterData* endpoint to accept an optional resolution, source, and horizon
- Changed the Introduction section:

    - Added information about timeseries resolutions
    - Added information about sources
    - Updated information about horizons

- Added a description of the *getPrognosis* endpoint in the Supplier section

v1.0-1 | 2018-07-10
"""""""""""""""""""

- Moved specifications to be part of the platform's Sphinx documentation:

    - Each API service is now documented in the docstring of its respective endpoint
    - Added sections listing all endpoints per version
    - Documentation includes specifications of **all** supported API versions (supported versions have a registered Flask blueprint)


v1.0-0 | 2018-07-10
"""""""""""""""""""

- Started change log
- Added Introduction section with notes regarding:

    - Authentication
    - Relevant roles for the API
    - Key notation
    - The addressing scheme for assets
    - Connection group notation
    - Timeseries notation
    - Prognosis notation
    - Units of timeseries data

- Added a description of the *getService* endpoint in the Introduction section
- Added a description of the *postMeterData* endpoint in the MDC section
- Added a description of the *getMeterData* endpoint in the Prosumer section
