Changeset: 5052d18264ac for MonetDB URL: http://dev.monetdb.org/hg/MonetDB?cmd=changeset;node=5052d18264ac Added Files: clients/iotclient/documentation/conclusion.rst Removed Files: clients/iotclient/documentation/future_work.rst clients/iotclient/documentation/streams_creation.rst Modified Files: clients/iotclient/documentation/index.rst clients/iotclient/documentation/iot_server_arguments.rst clients/iotclient/documentation/restful_resources.rst clients/iotclient/documentation/streams_data_types.rst clients/iotclient/src/Streams/datatypes.py clients/iotclient/src/Streams/jsonschemas.py Branch: iot Log Message:
Finished documentation and corrected regular expressions diffs (truncated from 432 to 300 lines): diff --git a/clients/iotclient/documentation/conclusion.rst b/clients/iotclient/documentation/conclusion.rst new file mode 100644 --- /dev/null +++ b/clients/iotclient/documentation/conclusion.rst @@ -0,0 +1,25 @@ +.. _future_work: + +********************** +Final Acknowledgements +********************** + +Future Work +=========== + +Currently the project is on a testing phase. More data types will also be added. + +Soon another web server will be built to implement an API for the baskets outputs from DataCell. + +.. _about-the-project: + +About the Project +================= + +.. _Send questions and suggestions to e-mail.: p.e.ferre...@cwi.nl + +Project maintained by Pedro Ferreira at CWI. `Send questions and suggestions to e-mail.`_ + +MonetDB source repository: https://dev.monetdb.org/hg/MonetDB + +MonetDB solutions: https://monetdbsolutions.com/ diff --git a/clients/iotclient/documentation/future_work.rst b/clients/iotclient/documentation/future_work.rst deleted file mode 100644 --- a/clients/iotclient/documentation/future_work.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _future_work: - - -****************** -Other information -****************** - -.. _future-work: - -Future Work -=========== - -Talk about it - -.. _about-the-project: - -About the Project -================= - -IOT stuff diff --git a/clients/iotclient/documentation/index.rst b/clients/iotclient/documentation/index.rst --- a/clients/iotclient/documentation/index.rst +++ b/clients/iotclient/documentation/index.rst @@ -16,7 +16,5 @@ Contents: introduction.rst iot_server_arguments.rst restful_resources.rst - streams_creation.rst streams_data_types.rst - future_work.rst - + conclusion.rst diff --git a/clients/iotclient/documentation/iot_server_arguments.rst b/clients/iotclient/documentation/iot_server_arguments.rst --- a/clients/iotclient/documentation/iot_server_arguments.rst +++ b/clients/iotclient/documentation/iot_server_arguments.rst @@ -53,7 +53,7 @@ Custom name of the host. By default is t Web Server Listening -------------------- -For security purposes, two web servers are created by the application. On the administration server are present operations to create and delete streams, while on application server the insert operations are present instead. The administration server should be listening on the host only, while the application server should be listening to the outside. +For security purposes, two web servers are created by the application. On the administration server are present operations to create and delete streams, while on application server the insert operations are present instead. The administration server should be listening on the host only, while the application server should be listening to all interfaces. **-ih - -ihost=** @@ -94,5 +94,3 @@ Name of the user to authenticate. By def **-dd - -ddatabase=** Name of database to use. By default is :code:`iotdb` database. - - diff --git a/clients/iotclient/documentation/restful_resources.rst b/clients/iotclient/documentation/restful_resources.rst --- a/clients/iotclient/documentation/restful_resources.rst +++ b/clients/iotclient/documentation/restful_resources.rst @@ -5,11 +5,125 @@ RESTful Resources ***************** -Introduction +Bellow is lested the available RESTful resource for both servers on IOT application. In case of error, the server will return the error message with the respective HTTP response code. + +.. important:: All the keywords provided on JSON must be lower case, as well the column data types. + +Administration Server +===================== + +The administration server provides resources to create and delete streams. Should be listening on the host only. .. _streams: /streams -============================= +-------- -Talk about this and the others +**GET** + +Returns a JSON file with details about all the streams currently created on the webserver. For each stream besides its schema and name, it provides the currently number of tuples inserted on the baskets per column, description of columns (`See data types <streams_data_types.html#data_types>`__), the flushing method (`See streams creation for details <streams_creation.html#creating_streams>`__). An example is shown bellow: + +.. code-block:: json + + [ + { + "tuples_inserted_per_basket": 1, + "columns": [ + { + "type": "real", + "name": "temperature", + "nullable": false + }, + { + "type": "text", + "name": "sensorid", + "nullable": false + } + ], + "flushing": { + "base": "tuple", + "number": 50 + }, + "stream": "measures", + "schema": "temperature" + } + ] + +/context +-------- + +**POST** + +Creates a stream using a pre-defined JSON schema. The JSON must include the stream's schema, the stream's name, the flushing method which can be either time or tuple based and the stream's columns. For tuple based flushing, the number of tuples to flush must be provided using the :code:`number` field. In time based flushing, the :code:`interval` field tells the time units between flushes and the :code:`unit` field must be "s", "m" or "h" for seconds, minutes or hours respectively. For columns `see data types for details <streams_data_types.html#data_types>`__. + +Bellow is the JSON used to create the stream in streams_: + +.. code-block:: json + + { + "schema": "temperature", + "stream": "measures", + "flushing": { + "base": "tuple", + "number": 50 + }, + "columns": [ + { + "type": "real", + "name": "temperature", + "nullable": false + }, + { + "type": "text", + "name": "sensorid", + "nullable": false + } + ] + } + +**DELETE** + +Deletes an existing stream. Only the stream's schema and name are required. To delete the stream in streams_ provide the following JSON: + +.. code-block:: json + + { + "schema": "temperature", + "stream": "measures" + } + +Application Server +================== + +The application server provides resources to make insertions on streams. Should be listening to all interfaces. + +/streams +-------- + +**GET** + +Same resource as streams_ . + +/stream/<schema_name>/<stream_name> +----------------------------------- + +**POST** + +Insert a batch of tuples on the provided stream in the URL. The insert must be an array of JSON object with pairs of column-value. All tuples are validaded according to the defined data types on each column. If there is an invalid tuple, none of the tuples is inserted. The implicit timestamp and the host identifier are automatically added. Bellow is shown an example to insert several tuples on the stream in streams_: + +.. code-block:: json + + [ + { + "sensorid": "living room", + "temperature": 32.6 + }, + { + "sensorid": "kitchen", + "temperature": 34.2 + }, + { + "sensorid": "bathroom", + "temperature": 28.9 + } + ] diff --git a/clients/iotclient/documentation/streams_creation.rst b/clients/iotclient/documentation/streams_creation.rst deleted file mode 100644 --- a/clients/iotclient/documentation/streams_creation.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _creating_streams: - - -**************** -Creating Streams -**************** - -Talk about streams creation diff --git a/clients/iotclient/documentation/streams_data_types.rst b/clients/iotclient/documentation/streams_data_types.rst --- a/clients/iotclient/documentation/streams_data_types.rst +++ b/clients/iotclient/documentation/streams_data_types.rst @@ -1,15 +1,111 @@ .. _data_types: - ******************** Available Data Types ******************** -Start talking about them +The following list contains the available data types for columns creation on the stream engine. The list was made as much compatible with `MonetDB's data types <https://www.monetdb.org/Documentation/Manuals/SQLreference/Datatypes>`_. For each column definiton, one of the types from the list must be provided along with its name. -.. _text: +By default a column is not nullable, but the pair :code:`"nullable": true` can be provided to make it nullable. There is also the possibility to add a default value if the column value is not present on a JSON insert tuple (ex: :code:`"default": "text"`). The default value is validated against the column's validation during the stream creation. -Text -==== +.. warning:: A column cannot be nullable and have a default value simultaneously. -This the text +.. important:: The provided keys as well as the types values on the JSON object during the creation request must be lowercase. + +Text Types +========== + +Text, String, Character Large Object +------------------------------------ + +MonetDB's string types with unbounded length. The insertion must be provided as a JSON string. + +Char, Character, Varchar, Character Varying +------------------------------------------- + +MonetDB's string types with a bounded length. The :code:`limit` parameter must be provided as an interger. The insertion must be provided as a JSON string within the limit. + +UUID +---- + +An *Universally Unique Identifier* according to `RFC 4122 <https://www.ietf.org/rfc/rfc4122.txt>`_. The insertion as a JSON string is validated against the regular expression :code:`^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`. + +Inet +---- + +An *IPv4* address. The insertion as a JSON string is validated against the regular expression :code:`^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$` with further semantic validation. + +URL +--- + +An *Uniform Resource Locator* as a specific type of an URI is validated according to `RFC 3987 <https://www.ietf.org/rfc/rfc3987.txt>`_. The insertion must also be a JSON String. + +Number Types +============ + +For all number types, a minimum and maximum values can be added for validation. + +Tinyint, Smallint, Int, Integer, Bigint, Hugeint +------------------------------------------------ + +Signed integers. The type name specifies its bit capacity. If the value is grater than the bit capacity, it will be truncated. The insertion must be provided as a JSON integer. + ++--------------+----------+ +| **Type** | **Size** | ++--------------+----------+ +| Tinyint | 8 | ++--------------+----------+ +| Smallint | 16 | ++--------------+----------+ +| Int, Integer | 32 | _______________________________________________ checkin-list mailing list checkin-list@monetdb.org https://www.monetdb.org/mailman/listinfo/checkin-list
