Issue 389 publish sensor data api documentation

documentation/api/change_log.rst

@@ -6,6 +6,24 @@ 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-0 | 2022-03-15
+"""""""""""""""""""
+
+- Added REST endpoint for listing sensors: `/sensors` (GET).
+- Added REST endpoint for managing sensor data: `/sensors/data` (GET, 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:
+
+    - *getConnection* -> use `/sensors` (GET) instead
+    - *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*
+    - *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"
+    - *postWeatherData* -> use `/sensors/data` (POST) instead
+    - *restoreData*
+
 v2.0-4 | 2022-01-04
 """""""""""""""""""
 
@@ -42,12 +60,12 @@ v2.0-2 | 2021-04-02
 v2.0-1 | 2021-02-19
 """""""""""""""""""
 
-- REST endpoints for managing users: `/users/` (GET), `/user/<id>` (GET, PATCH) and `/user/<id>/password-reset` (PATCH).
+- Added REST endpoints for managing users: `/users/` (GET), `/user/<id>` (GET, PATCH) and `/user/<id>/password-reset` (PATCH).
 
 v2.0-0 | 2020-11-14
 """""""""""""""""""
 
-- REST endpoints for managing assets: `/assets/` (GET, POST) and `/asset/<id>` (GET, PATCH, DELETE).
+- Added REST endpoints for managing assets: `/assets/` (GET, POST) and `/asset/<id>` (GET, PATCH, DELETE).
 
 
 v1.3-11 | 2022-01-05
@@ -80,7 +98,7 @@ 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 version below v2.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
 """""""""""""""""""
@@ -107,7 +125,7 @@ v1.3-5 | 2020-10-29
 - 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 4000 response.
+- 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
 """""""""""""""""""

documentation/api/dev.rst

@@ -0,0 +1,22 @@
+.. _dev:
+
+Developer API
+=============
+
+These endpoints are still under development and are subject to change in new releases.
+
+Summary
+-------
+
+.. qrefflask:: flexmeasures.app:create(env="documentation")
+    :modules: flexmeasures.api.dev.assets, flexmeasures.api.dev.sensors
+    :order: path
+    :include-empty-docstring:
+
+API Details
+-----------
+
+.. autoflask:: flexmeasures.app:create(env="documentation")
+    :modules: flexmeasures.api.dev.assets, flexmeasures.api.dev.sensors
+    :order: path
+    :include-empty-docstring:

documentation/api/introduction.rst

@@ -23,13 +23,13 @@ So if you are running FlexMeasures on your computer, it would be:
 
     https://localhost:5000/api
 
-At Seita, we run servers for our clients at:
+Let's assume we are running a server for a client at:
 
 .. code-block:: html
 
     https://company.flexmeasures.io/api
 
-where `company` is a hosting customer of ours. All their accounts' data lives on that server.
+where `company` is a client of ours. All their accounts' data lives on that server.
 
 We assume in this document that the FlexMeasures instance you want to connect to is hosted at https://company.flexmeasures.io.
 
@@ -40,17 +40,17 @@ Let's see what the ``/api`` endpoint returns:
     >>> import requests
     >>> res = requests.get("https://company.flexmeasures.io/api")
     >>> res.json()
-    {'flexmeasures_version': '0.4.0',
-     'message': 'For these API versions a public endpoint is available, listing its service. For example: /api/v1/getService and /api/v1_1/getService. An authentication token can be requested at: /api/requestAuthToken',
+    {'flexmeasures_version': '0.9.0',
+     'message': 'For these API versions a public endpoint is available, listing its service. For example: /api/v2_0/getService and /api/v3_0/getService. An authentication token can be requested at: /api/requestAuthToken',
      'status': 200,
-     'versions': ['v1', 'v1_1', 'v1_2', 'v1_3', 'v2_0']
+     'versions': ['v1', 'v1_1', 'v1_2', 'v1_3', 'v2_0', 'v3_0']
     }
 
-So this tells us which API versions exist. For instance, we know that the latest API version is available at
+So this tells us which API versions exist. For instance, we know that the latest API version is available at:
 
 .. code-block:: html
 
-    https://company.flexmeasures.io/api/v2_0
+    https://company.flexmeasures.io/api/v3_0
 
 
 Also, we can see that a list of endpoints which are available at (a version of) the FlexMeasures web service can be obtained by sending a ``getService`` request. An optional field "access" can be used to specify a user role for which to obtain only the relevant services.
@@ -374,10 +374,10 @@ Technically, this is equal to:
 
 This intuitive convention allows us to reduce communication by sending univariate timeseries as arrays.
 
-Notation for v1
-"""""""""""""""
+Notation for v1, v2 and v3
+""""""""""""""""""""""""""
 
-For version 1 and 2 of the API, only equidistant timeseries data is expected to be communicated. Therefore:
+For version 1, 2 and 3 of the API, only equidistant timeseries data is expected to be communicated. Therefore:
 
 - only the array notation should be used (first notation from above),
 - "start" should be a timestamp on the hour or a multiple of the sensor resolution thereafter (e.g. "16:10" works if the resolution is 5 minutes), and
@@ -496,19 +496,25 @@ Resolutions
 
 Specifying a resolution is redundant for POST requests that contain both "values" and a "duration" ― FlexMeasures computes the resolution by dividing the duration by the number of values.
 
-When POSTing data, FlexMeasures checks this computed resolution against the required resolution of the assets which are posted to. If these can't be matched (through upsampling), an error will occur.
+When POSTing data, FlexMeasures checks this computed resolution against the required resolution of the sensors which are posted to. If these can't be matched (through upsampling), an error will occur.
 
 GET requests (such as *getMeterData*) return data in the resolution which the sensor is configured for.
 A "resolution" may be specified explicitly to obtain the data in downsampled form, 
 which can be very beneficial for download speed. The specified resolution needs to be a multiple
-of the asset's resolution, e.g. hourly or daily values if the asset's resolution is 15 minutes.
+of the sensor's resolution, e.g. hourly or daily values if the sensor's resolution is 15 minutes.
 
 .. _units:
 
 Units
 ^^^^^
 
-Valid units for timeseries data in version 1 of the API are "MW" only.
+From API version 3 onwards, we are much more flexible with sent units.
+A valid unit for timeseries data is any unit that is convertible to the configured sensor unit registered in FlexMeasures.
+So, for example, you can send timeseries data with "W" unit to a "kW" sensor.
+And if you wish to do so, you can even send a timeseries with "kWh" unit to a "kW" sensor.
+In this case, FlexMeasures will convert the data using the resolution of the timeseries.
+
+For API versions 1 and 2, the unit sent needs to be an exact match with the sensor unit, and only "MW" is allowed for power sensors.
 
 .. _signs:
 

documentation/api/v3_0.rst

@@ -0,0 +1,20 @@
+.. _v3_0:
+
+Version 3.0
+===========
+
+Summary
+-------
+
+.. qrefflask:: flexmeasures.app:create(env="documentation")
+    :modules: flexmeasures.api.v3_0.implementations.sensors, flexmeasures.api.v3_0.implementations.users
+    :order: path
+    :include-empty-docstring:
+
+API Details
+-----------
+
+.. autoflask:: flexmeasures.app:create(env="documentation")
+    :modules: flexmeasures.api.v3_0.implementations.sensors, flexmeasures.api.v3_0.implementations.users
+    :order: path
+    :include-empty-docstring:

documentation/getting-started.rst

@@ -195,7 +195,7 @@ First, you can load in data from a file (CSV or Excel) via the ``flexmeasures``
 
 This assumes you have a file `my-data.csv` with measurements, which was exported from some legacy database, and that the data is about our sensor with ID 1. This command has many options, so do use its ``--help`` function.
 
-Second, you can use the `POST /api/v2_0/postMeterData <api/v2_0.html#post--api-v2_0-postMeterData>`_ endpoint in the FlexMeasures API to send meter data.
+Second, you can use the `POST /api/v3_0/sensors/data <api/v3_0.html#post--api-v3_0-sensors-data>`_ endpoint in the FlexMeasures API to send meter data.
 
 Finally, you can tell FlexMeasures to create forecasts for your meter data with the ``flexmeasures add forecasts`` command, here is an example:
 

documentation/index.rst

@@ -128,11 +128,13 @@ The platform operator of FlexMeasures can be an Aggregator.
     :maxdepth: 1
 
     api/introduction
+    api/v3_0
     api/v2_0
     api/v1_3
     api/v1_2
     api/v1_1
     api/v1
+    api/dev
     api/change_log
 
 .. toctree::

documentation/tut/building_uis.rst

@@ -20,7 +20,7 @@ This tutorial will show how the FlexMeasures API can be used from JavaScript to
 Get an authentication token
 -----------------------
 
-FlexMeasures provides the `POST /api/v2_0/requestAuthToken <../api/v2_0.html#post--api-v2_0-requestAuthToken>`_ endpoint, as discussed in :ref:`api_auth`. 
+FlexMeasures provides the `POST /api/requestAuthToken <../api/v2_0.html#post--api-v2_0-requestAuthToken>`_ endpoint, as discussed in :ref:`api_auth`.
 Here is a JavaScript function to call it:
 
 .. code-block:: JavaScript

documentation/tut/forecasting_scheduling.rst

@@ -116,7 +116,7 @@ Getting power forecasts (prognoses)
 
 Prognoses (the USEF term used for power forecasts) are used by FlexMeasures to determine the best control signals to valorise on balancing opportunities.
 
-You can access forecasts via the FlexMeasures API at `GET  /api/v2_0/getPrognosis <../api/v2_0.html#get--api-v2_0-getPrognosis>`_. 
+You can access forecasts via the FlexMeasures API at `GET  /api/v2_0/getPrognosis <../api/v2_0.html#get--api-v2_0-getPrognosis>`_.
 Getting them might be useful if you want to use prognoses in your own system, or to check their accuracy against meter data, i.e. the realised power measurements.
 The FlexMeasures UI also lists forecast accuracy, and visualises prognoses and meter data next to each other.