first draft of REST API design idea

rest-api-idea.txt

@@ -0,0 +1,133 @@
+To be implemented as a REST API
+
+========== Read data from configured channels ==========
+
+# i is a user-specified channel ID [1-7]
+# if the channel specified is not configured, return an error
+GET /data/channel/:i -> {
+    
+    return {
+        id,
+        value (in °C)
+        timestamp
+    }
+
+}
+
+# get the {id, value} of all configured channels, and a timestamp
+GET /data/channels -> {
+
+    return {
+        array of "/data/channel/:i" without the individual timestamp fields
+        timestamp
+    }
+}
+
+# returns the `latest' set of Pi-specific values that are used during signal conversion
+GET /data/ratio -> {
+
+    return {
+        vref,
+        vadj,
+        pi_vdd,
+        timestamp
+    }
+
+}
+
+# returns all data fields that a user may want to log/access
+GET /data/all -> {
+
+    return {
+        /data/channels without timestamp
+        /data/ratio without timestamp
+        timestamp
+    }
+}
+
+========== Read configuration info ==========
+
+# returns the config variables/options used to configure this channel
+# if the channel, specified by i is not configured, an error is returned.
+GET /config/channel/:i -> {
+
+    return {
+        thermocouple type,
+        offset,
+        gain,
+        filter settings, etc.
+
+        timestamp
+    }
+}
+
+# returns an array of all configured channels
+GET /config/channels -> {
+
+    return {
+        array of "/config/channel/:i" without individual timestamps
+        timestamp
+    }
+}
+
+# returns config variables/options used to set up device behaviour
+GET /config/device -> {
+
+    return {
+        HTTP_PORT,
+        WS_PORT,
+        debug_mode, etc.
+    }
+}
+
+# returns the DB map object.
+# since most DB solutions work slightly differently, the DB configuration
+# is saved as just a map[string][string], and the specified DB type's associated code
+# checks the map for entries it requires, upon start-up.
+# This can leak secret passwords etc so this endpoint will not be reachable
+# by default, and instead has to be manually enabled in the config fields
+# under the [TH7] section.
+GET /config/db -> {
+
+    return {
+        DB map
+    }
+}
+
+========== write configuration info ==========
+
+=== The POST request payload should be of the form:
+=== { key: value } and several options can be specified at once like such:
+=== [{ key1: value }, { key2: value}, {key3: value }]
+
+# write device-specific key:value pair(s) to the device config
+# returns success or error 
+POST /config/device -> {
+
+    return {
+        success/error status of key:value change
+        timestamp
+    }    
+}
+
+# write channel-specific key:value pair(s) to the channel/:i config
+# returns success or error 
+POST /config/channel/:i -> {
+
+    return {
+        success/error status of key:value change
+        timestamp
+    }
+}
+
+# write DB-specific key:value pair(s) to the DB config
+# returns success or error 
+# this endpoint must be manually enabled in the device config fields
+# under the [TH7] section
+POST /config/db -> {
+
+    return {
+        success/error status of key:value change
+        timestamp
+    }
+}