[{"_1":2,"_160":-5,"_161":-5},"loaderData",{"_3":4,"_17":18,"_25":26,"_139":140},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7,"_13":14,"_15":16},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","theme","system","contrast","normal","routes/_layout",{"_19":-5,"_20":21,"_22":21,"_23":11,"_24":21},"username","isAskGordonEnabled",true,"isUsingNewTemplate","showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_27":28,"_29":-5,"_30":11,"_31":11,"_32":33,"_34":35,"_36":-5,"_37":11,"_38":39,"_88":-5,"_89":90,"_128":-5,"_129":11,"_130":21,"_131":11,"_132":-5,"_133":11,"_134":-5,"_135":136,"_137":91,"_138":-7},"canonicalUrl","https://hub.docker.com/r/bfolkens/siridb-http/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","bfolkens","reponame","siridb-http","cloudBuildSource","isAutobuildsAvailable","repo",{"_40":41,"_42":43,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":55,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":74,"_79":21,"_80":81,"_85":33,"_86":87},"categories",[],"content_types",[44],"image","date_registered","2018-01-18T13:01:41.149633Z","description","HTTP API for communicating with SiriDB using JSON, MsgPack, QPack, CSV or Socket.io","is_private","last_updated","2018-01-18T14:25:30.316228Z","last_modified","2024-10-16T13:48:34.145251Z","media_types",[56],"application/vnd.docker.container.image.v1+json","name","pull_count",1070,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","# SiriDB HTTP\n![alt SiriDB HTTP](/siridb-http.png?raw=true)\n\nSiriDB HTTP provides a HTTP API and optional web interface for [SiriDB](https://github.com/transceptor-technology/siridb-server).\n\n> Note: Since version 2.0.0 SiriDB HTTP is written in Go. For the 1.x version in Python you should go to\n> this [release tag](https://github.com/transceptor-technology/siridb-http/tree/1.0.7).\n\n---------------------------------------\n * [Features](#features)\n * [Installation](#installation)\n * [Pre-compiled](#pre-compiled)\n * [Compile from source](#compile-from-source)\n * [Configuration](#configuration)\n * [Autorun on startup](#autorun-on-startup)\n * [Multi server support](#multi-server-support)\n * [HTTP API](#http-api)\n * [Content Types](#content-types)\n * [Database info](#database-info)\n * [Authentication](#authentication)\n * [Session authentication](#session-authentication)\n * [Fetch](#fetch)\n * [Login](#login)\n * [Logout](#logout)\n * [Basic authentication](#basic-authentication)\n * [Query](#query)\n * [Insert](#insert)\n * [JSON, MsgPack, QPack](#insert-json)\n * [CSV](#insert-csv)\n * [List format](#list-format)\n * [Table format](#table-format)\n * [Socket.io](#socketio)\n * [Web Interface](#web-interface)\n * [SSL (HTTPS)](#ssl-https)\n---------------------------------------\n\n## Features\n - Optional Web interface for sending queries and inserting data\n - SSL (HTTPS) support\n - Optional Basic Authentication\n - Support for JSON, MsgPack, QPack and CSV\n - IPv6 support\n - Socket.io support\n\n\n## Installation\nSiriDB HTTP 2.x can be compiled from source or, for most systems, you can simply download a pre-compiled binary.\n\n### Pre-compiled\nGo to https://github.com/transceptor-technology/siridb-http/releases/latest and download the binary for your system.\nIn this documentation we refer to the binary as `siridb-http`. On Linux/OSX it might be required to set the execution flag:\n```\n$ chmod +x siridb-http_X.Y.Z_OS_ARCH.bin\n```\n\nYou might want to copy the binary to /usr/local/bin and create a symlink like this:\n```\n$ sudo cp siridb-http_X.Y.Z_OS_ARCH.bin /usr/local/bin/\n$ sudo ln -s /usr/local/bin/siridb-http_X.Y.Z_OS_ARCH.bin /usr/local/bin/siridb-http\n```\n> Note: replace `X.Y.Z_OS_ARCH` with your binary, for example `2.0.0_linux_amd64`\n\n### Compile from source\n> Before compiling from source make sure **go**, **npm** and **git** are installed and your [$GOPATH](https://github.com/golang/go/wiki/GOPATH) is set.\n\nClone the project using git. (we assume git is installed)\n```\ngit clone https://github.com/transceptor-technology/siridb-http\n```\n\nMake sure less is installed:\n```\n$ sudo npm install -g less less-plugin-clean-css\n```\n\nThe gobuild.py script can be used to build the binary:\n```\n$ ./gobuild.py -i -l -w -b -p\n```\n\nOr, if you want the development version which uses original files from /build and /static instead of build-in files:\n```\n$ ./gobuild.py -i -l -w -b -d\n```\n\n## Configuration\nFor running SiriDB HTTP a configuration file is required and should be provided using the `-c` or `--config` argument. The easiest way to create a configuration file is to save the output from\nsiridb-http to a file:\n\n> Note: you might want to switch to root and later create a service to automically start SiriDB HTTP at startup.\n\nSwitch to root or skip this step if you want to save the configuration file with your current user.\n```\n$ sudo su -\n```\n\nSave a template configuration file to for example ~/.siridb-http.conf.\n```\n$ siridb-http > ~/.siridb-http.conf\n```\n\nNow edit the file with you favorite editor and at least set the `user`, `password` and `dbname`.\nWhen the configuration is saved you can start the server using:\n```\n$ siridb-http -c ~/.siridb-http.conf\n```\n\n### Autorun on startup\nDepending on your OS and subsystem you can create a service to start SiriDB HTTP.\nThis is an example of how to do this using systemd which is currently the default for Ubuntu:\n\nFirst create the service file: (you might need to change the ExecStart line)\n```\n$ sudo cat > /lib/systemd/system/siridb-http.service < Note: when a string in CSV contains a comma (,) then the string must be wrapped between double quotes.\n> If double quotes are also required in a string, the double quote should be escaped with a second double quote.\n\n### Database info\nWith the `/db-info` URI, database and version information can be asked.\n```\ntype: GET or POST\nuri: /db-info\nheader: Content-Type: 'application/json'\n```\n\nResponse:\n```json\n{\n \"dbname\": \"my_database-name\",\n \"timePrecision\": \"database time precision: s, ms, us or ns\",\n \"version\": \"SiriDB Server version, for example: 2.0.18\",\n \"httpServer\": \"SiriDB HTTP version, for example: 2.0.0\"\n}\n```\n\n> Note that `version` does not guarantee that each SiriDB server in a cluster is running the same version.\n\n### Authentication\nAuthentication is required when `require_authentication` is set to `True` in the configuration file. When authentication is not required, the `/insert` and `/query` URIs can be used directly without any authentication as long as the user configured in the configuration file has privileges to perform the request.\n\n#### Session authentication\nSiriDB HTTP has session support and exposes the following URIs for handling session authentication:\n- /auth/fetch\n- /auth/login\n- /auth/logout\n\n> Note: in the examples below we use 'application/json' as Content-Type but the following alternatives\n> are also allowed: 'application/x-msgpack', 'application/x-qpack' and 'application/csv'.\n\n##### Fetch\nFetch can be used to retrieve the current session user.\n```\ntype: GET or POST\nuri: /auth/fetch\nheader: Content-Type: 'application/json'\n```\nThe response contains the current user and a boolean value to indicate if authentication is required. In case no user is logged on and authentication is required, the value for `user` will be `null`.\n\nExample response:\n```json\n{\n \"user\": \"logged_on_username_or_null\",\n \"authRequired\": true\n}\n```\n\n##### Login\nLogin can be used to authenticate and create a SiriDB database user. If the option `enable_multi_user` in the configuration file is set to `True`, any database user can be used. In case multi user support is turned off, the only allowed user is the one configured in the configuration file.\n\n```\ntype: POST\nuri: /auth/login\nheader: Content-Type: 'application/json'\nbody: {\"username\": , \"password\": }\n```\n\nSuccess response:\n```json\n{\n \"user\": \"logged_on_username\"\n}\n```\n\nIn case authentication has failed, error code 422 will be returned and the body will contain an appropriate error message.\n\n##### Logout\nWhen calling this uri the current session will be cleared.\n```\ntype: GET or POST\nuri: /auth/logout\nheader: Content-Type: 'application/json'\n```\nResponse:\n```json\n{\n \"user\": null\n}\n```\n\n#### Basic authentication\nAs an alternative to session authentication it is possible to use basic authentication. To allow basic authentication the option `enable_basic_auth` must be set to `True` in the configuration file.\n\nExample Authorization header for username *iris* with password *siri*:\n```\nAuthorization: Basic aXJpczpzaXJp\n```\n\n### Query\nThe `/query` POST handler can be used for querying SiriDB. SiriDB HTTP supports multiple formats that can be used by setting the `Content-Type` in the header.\n```\ntype: POST\nuri: /query\nheader: Content-Type: 'application/json'\nbody: {\"query\": , \"timeout\": }\n```\n\nExample body:\n```json\n{\n \"query\": \"select mean(1h) => difference() from 'my-series'\"\n}\n```\n\n### Insert\nThe `/insert` POST handler can be used for inserting data into SiriDB. The same content types as for queries are supported. Both MsgPack and QPack are similar to JSON except that the data is packed to a byte string. Therefore we only explain JSON and CSV data here. *(Note: in the examples below we use a second time-precision)*\n\n#### Insert JSON\nThe preferred json layout is as following: (this is the layout which is returned by SiriDB on a select query)\n```json\n{\n \"my-series-01\": [[1493126582, 4.2], ...],\n ...\n}\n```\n\nOptionally the following format can be used:\n```json\n[\n {\n \"name\": \"my-series-01\",\n \"points\": [[1493126582, 4.2], ...]\n },\n ...\n]\n```\n\n#### Insert CSV\nCSV data is allowed in two formats which we call the list and table format.\n\n##### List format\nWhen using the list format, each row in the csv should contain a series name, timestamp and value.\n\nExample list:\n```csv\nSeries 001,1440138931,100\nSeries 003,1440138931,8.0\nSeries 001,1440140932,40\nSeries 002,1440140932,9.3\n```\n##### Table format\nA table format is more compact, especially if multiple series share points with equal timestamps. The csv should start with an empty field that is indicated with the first comma.\n\nExample table:\n```csv\n,Series 001,Series 002,Series 003\n1440138931,100,,8.0\n1440140932,40,9.3,\n```\n\n## Socket.io\nSiriDB HTTP has socket.io support when `enable_socket_io` is set to `True` in the configuration file.\n\nFor Socket.io the following events are available:\n- `db-info`\n- `auth fetch`\n- `auth login`\n- `auth logout`\n- `query`\n- `insert`\n\nThe result for an event contains a status code and data object. The status codes are equal to HTTP status codes. For example the success code is 200.\nWhen the status code is anything other than 200, the data object will be a string representing the error message.\n\nExample of using Socket.io with HTML/JavaScript:\n```html\n\n\n\n\n\n\n\n\n```\n\n## Web interface\nSiriDB has an optional web interface that can be enabled by setting `enable_web` to `True`. This web interface will ask for user authentication if `enable_authentication` is set to `True`. Only the `user` that is configured in the configuration file is allowed to login unless `enable_multi_user` is set to `True`.\n\nThe Web interface allows you to run queries and insert data using JSON format.\n\n## SSL (HTTPS)\nSSL (HTTPS) support can be enabled by setting `enable_ssl` to `True`. When enabled the `crt_file` and `key_file` in section `[SSL]` must be set.\n\n","has_starred","hub_user","immutable_tags_settings",{"_75":11,"_76":77},"enabled","rules",[78],".*","is_automated","permissions",{"_82":21,"_83":11,"_84":11},"read","write","admin","user","storage_size",6827606,"orgData","recentTags",[91],{"_92":44,"_93":94,"_95":96,"_97":98,"_99":100,"_50":117,"_118":94,"_119":33,"_120":56,"_57":121,"_122":123,"_124":-5,"_125":117,"_126":115,"_127":21},"content_type","creator",569100,"full_size",6824723,"id",20840114,"images",[101],{"_102":103,"_104":105,"_106":107,"_108":-5,"_109":-5,"_110":111,"_112":107,"_113":-5,"_114":96,"_63":115,"_116":-5},"architecture","amd64","digest","sha256:70a04cfb68229b72f22e10759af8d670a30c5b5f0cd4bacea0717359bbf309b0","features","","last_pulled","last_pushed","os","linux","os_features","os_version","size","inactive","variant","2018-01-18T14:25:29.436102Z","last_updater","last_updater_username","media_type","latest","repository",3603759,"tag_last_pulled","tag_last_pushed","tag_status","v2","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"selectedTag","attestationsUrl","routes/_layout.r.$namespace.$reponame.tags",{"_38":141,"_148":149,"_135":158,"_159":11},{"_40":142,"_42":143,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":144,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":145,"_79":21,"_80":147,"_85":33,"_86":87},[],[44],[56],{"_75":11,"_76":146},[78],{"_82":21,"_83":11,"_84":11},"tags",{"_150":64,"_151":-5,"_152":-5,"_153":154},"count","next","previous","results",[155],{"_92":44,"_93":94,"_95":96,"_97":98,"_99":156,"_50":117,"_118":94,"_119":33,"_120":56,"_57":121,"_122":123,"_124":-5,"_125":117,"_126":115,"_127":21},[157],{"_102":103,"_104":105,"_106":107,"_108":-5,"_109":-5,"_110":111,"_112":107,"_113":-5,"_114":96,"_63":115,"_116":-5},[],"canDeleteTags","actionData","errors"]

bfolkens/siridb-http

Tags for bfolkens/siridb-http