Skip to content

HTTP Endpoints

Jump to bottom
chengshiwen edited this page Aug 15, 2024 · 14 revisions

HTTP Endpoints v2.5.12

The Influx Proxy API provides a simple way to interact with the influx proxy server. It uses HTTP response codes, HTTP authentication, and basic authentication, and responses are returned in JSON.

HTTP Endpoints

Endpoint Description
/ping Use /ping to check the status of your InfluxDB Proxy instance and your version of InfluxDB Proxy.
/query Use /query to query data and manage databases and measurements.
/write Use /write to write data to a pre-existing database.
/api/v2/query Use /api/v2/query to query data in InfluxDB 1.8.0+ using the InfluxDB 2.0 API and Flux.
/api/v2/write Use /api/v2/write to write data to InfluxDB 1.8.0+ using the InfluxDB 2.0 API.
/health Use /health to view health status of all influxdb backends.
/replica Use /replica to query replica backends with database and measurement.
/encrypt Use /encrypt to encrypt plain username and password.
/decrypt Use /decrypt to decrypt ciphered username and password.
/rebalance Use /rebalance to rebalance measurements of specific circle.
/recovery Use /recovery to recovery measurements from one circle to another circle.
/resync Use /resync to resync measurements with each other.
/cleanup Use /cleanup to cleanup misplaced measurements of specific circle.
/transfer/state Use /transfer/state to get or set transfer state.
/transfer/stats Use /transfer/stats to query transfer stats when transferring.
/api/v1/prom/read Use /api/v1/prom/read for prometheus remote read.
/api/v1/prom/write Use /api/v1/prom/write for prometheus remote write.
/metrics Use /metrics for prometheus-formatted metrics.
/debug/pprof Use /debug/pprof to generate profiles for troubleshooting.

The following sections assume your InfluxDB Proxy instance is running on 127.0.0.1:7076 and HTTPS is not enabled.

/ping HTTP endpoint

official reference:

/query HTTP endpoint

official reference:

/write HTTP endpoint

official reference:

/api/v2/query HTTP endpoint

official reference:

/api/v2/write HTTP endpoint

official reference:

/health HTTP endpoint

Definition

GET http://127.0.0.1:7076/health

Query string parameters

Query String Parameter Optional/Required Description
stats=false Optional Return more detailed stats information
pretty=true Optional Enables pretty-printed JSON output.
u=<username> Optional if you haven't enabled authentication Set the username for authentication if you've enabled authentication.
p=<password> Optional if you haven't enabled authentication Set the password for authentication if you've enabled authentication.

Example

$ curl 'http://127.0.0.1:7076/health?stats=true&pretty=true'

{
    "checks": [],
    "circles": [
        {
            "circle": {
                "id": 0,
                "name": "circle-1",
                "active": true,
                "write_only": false
            },
            "backends": [
                {
                    "name": "influxdb-1-1",
                    "url": "http://127.0.0.1:8086",
                    "active": true,
                    "backlog": false,
                    "rewriting": false,
                    "write_only": false,
                    "healthy": true,
                    "stats": {
                        "db1": {
                            "incorrect": 0,
                            "inplace": 2,
                            "measurements": 2
                        },
                        "db2": {
                            "incorrect": 0,
                            "inplace": 2,
                            "measurements": 2
                        }
                    }
                }
            ]
        },
        ...
    ],
    "message": "ready for queries and writes",
    "name": "influx-proxy",
    "status": "pass",
    "version": "2.5.12"
}

Field description:

circle:

  • id: circle id
  • name: circle name
  • active: whether all influxdb instances of circle are active
  • write_only: whether circle is write-only (at least one influxdb instance is write-only)

backends:

  • name: influxdb name
  • url: influxdb url
  • active: whether the influxdb is running
  • backlog: is there failed data in the cache file to influxdb
  • rewriting: whether the cache data is being rewritten to influxdb
  • write_only: whether influxdb is write-only
  • healthy: whether influxdb is healthy, it's true when each incorrect equals 0 in stats
  • stats: influxdb stats of databases
    • db: influxdb database
      • incorrect: number of measurements which should not be stored on this influxdb
        • it's healthy when incorrect equals 0
      • inplace: number of measurements which should be stored on this influxdb
        • it's healthy when inplace equals the number of measurements in this database
      • measurements: number of measurements in this database
        • measurements = incorrect + inplace
        • the number of measurements in each influxdb instance is roughly the same, indicating that the data store is load balanced

/replica HTTP endpoint

Definition

GET http://127.0.0.1:7076/replica

Query string parameters

Query String Parameter Optional/Required Description
db=<database> Required Database name for replica backends query.
mm=<measurement> Required Measurement name for replica backends query (meas is still valid).
pretty=true Optional Enables pretty-printed JSON output.
u=<username> Optional if you haven't enabled authentication Set the username for authentication if you've enabled authentication.
p=<password> Optional if you haven't enabled authentication Set the password for authentication if you've enabled authentication.

Example

$ curl 'http://127.0.0.1:7076/replica?db=db1&mm=cpu1&pretty=true'

[
    {
        "backend": {
            "name": "influxdb-1-2",
            "url": "http://127.0.0.1:8087"
        },
        "circle": {
            "id": 0,
            "name": "circle-1"
        }
    },
    {
        "backend": {
            "name": "influxdb-2-2",
            "url": "http://127.0.0.1:8089"
        },
        "circle": {
            "id": 1,
            "name": "circle-2"
        }
    }
]

/encrypt HTTP endpoint

Definition

GET http://127.0.0.1:7076/encrypt

Query string parameters

Query String Parameter Optional/Required Description
text=<text> Required The plain text to encrypt.

Example

$ curl -G 'http://127.0.0.1:7076/encrypt' --data-urlencode 'text=admin'

YgvEyuPZlDYAH8sGDkC!Ag

/decrypt HTTP endpoint

Definition

GET http://127.0.0.1:7076/decrypt

Query string parameters

Query String Parameter Optional/Required Description
key=<key> Required The key to encrypt and decrypt, default is consistentcipher.
text=<text> Required The ciphered text to decrypt.

Example

$ curl 'http://127.0.0.1:7076/decrypt?key=consistentcipher&text=YgvEyuPZlDYAH8sGDkC!Ag'

admin

/rebalance HTTP endpoint

Definition

POST http://127.0.0.1:7076/rebalance

Query string parameters

Query String Parameter Optional/Required Description
circle_id=0 Required Circle index started from 0.
operation=<operation> Required Operation type, valid options are add or rm.
dbs=<dbs> Optional Comma-separated database list while using all databases if empty.
worker=5 Optional Concurrent worker's number when transfer, default is 5.
batch=20000 Optional Query batch when transfer, default is 20000.
since=<since> Optional Query data from a 10-digital unix time, default is 0 for all data.
ha_addrs=<ha_addrs> Required if at least two InfluxDB Proxy instances are running High available addresses (host1:port1,host2:port2...) of all running InfluxDB Proxy for two instances at least, comma-separated.
u=<username> Optional if you haven't enabled authentication Set the username for authentication if you've enabled authentication.
p=<password> Optional if you haven't enabled authentication Set the password for authentication if you've enabled authentication.

Request body

Json body for describing backends to remove, required when operation is rm

{
    "backends": [
        {
            "name": "influxdb-1-2",
            "url": "http://127.0.0.1:8087",
            "username": "",
            "password": "",
            "auth_encrypt": false
        }
    ]
}

Example

Rebalance measurements of circle specified by circle_id after adding backends and restarting InfluxDB Proxy instance

$ curl -X POST 'http://127.0.0.1:7076/rebalance?circle_id=0&operation=add'

accepted

Rebalance measurements of circle specified by circle_id after adding backends, while there are two running InfluxDB Proxy instances for high availability

$ curl -X POST 'http://127.0.0.1:7076/rebalance?circle_id=0&operation=add&ha_addrs=127.0.0.1:7076,127.0.0.1:7077'

accepted

Rebalance measurements of circle specified by circle_id after removing backends, if there is only one running InfluxDB Proxy instances

$ curl -X POST 'http://127.0.0.1:7076/rebalance?circle_id=0&operation=rm&worker=10' -H 'Content-Type: application/json' -d \
'{
    "backends": [
        {
            "name": "influxdb-1-2",
            "url": "http://127.0.0.1:8087",
            "username": "",
            "password": "",
            "auth_encrypt": false
        }
    ]
}'

accepted

/recovery HTTP endpoint

Definition

POST http://127.0.0.1:7076/recovery

Query string parameters

Query String Parameter Optional/Required Description
from_circle_id=0 Required From circle index started from 0.
to_circle_id=1 Required To circle index started from 0.
backend_urls=<backend_urls> Optional Comma-separated backend urls to recovery while using all backends of circle specified by to_circle_id if empty.
dbs=<dbs> Optional Comma-separated database list while using all databases if empty.
worker=5 Optional Concurrent worker's number when transfer, default is 5.
batch=20000 Optional Query batch when transfer, default is 20000.
since=<since> Optional Query data from a 10-digital unix time, default is 0 for all data.
ha_addrs=<ha_addrs> Required if at least two InfluxDB Proxy instances are running High available addresses (host1:port1,host2:port2...) of all running InfluxDB Proxy for two instances at least, comma-separated.
u=<username> Optional if you haven't enabled authentication Set the username for authentication if you've enabled authentication.
p=<password> Optional if you haven't enabled authentication Set the password for authentication if you've enabled authentication.

Example

Recovery all backends of circle 1 from circle 0

$ curl -X POST 'http://127.0.0.1:7076/recovery?from_circle_id=0&to_circle_id=1'

accepted

Only recovery backend http://127.0.0.1:8089 in circle 1 from circle 0

$ curl -X POST 'http://127.0.0.1:7076/recovery?from_circle_id=0&to_circle_id=1&backend_urls=http://127.0.0.1:8089'

accepted

/resync HTTP endpoint

Definition

POST http://127.0.0.1:7076/resync

Query string parameters

Query String Parameter Optional/Required Description
dbs=<dbs> Optional Comma-separated database list while using all databases if empty.
worker=5 Optional Concurrent worker's number when transfer, default is 5.
batch=20000 Optional Query batch when transfer, default is 20000.
since=<since> Optional Query data from a 10-digital unix time, default is 0 for all data (tick is still valid).
ha_addrs=<ha_addrs> Required if at least two InfluxDB Proxy instances are running High available addresses (host1:port1,host2:port2...) of all running InfluxDB Proxy for two instances at least, comma-separated.
u=<username> Optional if you haven't enabled authentication Set the username for authentication if you've enabled authentication.
p=<password> Optional if you haven't enabled authentication Set the password for authentication if you've enabled authentication.

Example

$ curl -X POST 'http://127.0.0.1:7076/resync?worker=10'

accepted

/cleanup HTTP endpoint

Definition

POST http://127.0.0.1:7076/cleanup

Query string parameters

Query String Parameter Optional/Required Description
circle_id=0 Required Circle index started from 0.
worker=5 Optional Concurrent worker's number when transfer, default is 5.
ha_addrs=<ha_addrs> Required if at least two InfluxDB Proxy instances are running High available addresses (host1:port1,host2:port2...) of all running InfluxDB Proxy for two instances at least, comma-separated.
u=<username> Optional if you haven't enabled authentication Set the username for authentication if you've enabled authentication.
p=<password> Optional if you haven't enabled authentication Set the password for authentication if you've enabled authentication.

Example

$ curl -X POST 'http://127.0.0.1:7076/cleanup?circle_id=0&worker=10'

accepted

/transfer/state HTTP endpoint

Definition

GET http://127.0.0.1:7076/transfer/state

POST http://127.0.0.1:7076/transfer/state

Query string parameters

Query String Parameter Optional/Required Description
resyncing=true Optional Set resyncing state of proxy.
circle_id=0 Optional Circle index to set transferring state, started from 0.
transferring=false Optional Set transferring state of circle specified by circle_id.
pretty=true Optional Enables pretty-printed JSON output.
u=<username> Optional if you haven't enabled authentication Set the username for authentication if you've enabled authentication.
p=<password> Optional if you haven't enabled authentication Set the password for authentication if you've enabled authentication.

Example

Get transfer state

$ curl 'http://127.0.0.1:7076/transfer/state?pretty=true'

{
    "circles": [
        {
            "id": 0,
            "name": "circle-1",
            "transferring": false
        },
        {
            "id": 1,
            "name": "circle-2",
            "transferring": false
        }
    ],
    "resyncing": false
}

Set resyncing state of proxy

$ curl -X POST 'http://127.0.0.1:7076/transfer/state?resyncing=true&pretty=true'

{
    "resyncing": true
}

Set transferring state of circle 0

$ curl -X POST 'http://127.0.0.1:7076/transfer/state?circle_id=0&transferring=true&pretty=true'

{
    "circle": {
        "id": 0,
        "name": "circle-1",
        "transferring": true
    }
}

/transfer/stats HTTP endpoint

Definition

GET http://127.0.0.1:7076/transfer/stats

Query string parameters

Query String Parameter Optional/Required Description
circle_id=0 Required Circle index started from 0.
type=<type> Required Stats type, valid options are rebalance, recovery, resync or cleanup.
pretty=true Optional Enables pretty-printed JSON output.
u=<username> Optional if you haven't enabled authentication Set the username for authentication if you've enabled authentication.
p=<password> Optional if you haven't enabled authentication Set the password for authentication if you've enabled authentication.

Example

$ curl 'http://127.0.0.1:7076/transfer/stats?circle_id=0&type=rebalance&pretty=true'

{
    "http://127.0.0.1:8086": {
        "database_total": 0,
        "database_done": 0,
        "measurement_total": 0,
        "measurement_done": 0,
        "transfer_count": 0,
        "inplace_count": 0
    },
    "http://127.0.0.1:8087": {
        "database_total": 0,
        "database_done": 0,
        "measurement_total": 0,
        "measurement_done": 0,
        "transfer_count": 0,
        "inplace_count": 0
    }
}

/api/v1/prom/read HTTP endpoint

official reference:

/api/v1/prom/write HTTP endpoint

official reference:

/metrics HTTP endpoint

official reference:

/debug/pprof HTTP endpoint

official reference:

Clone this wiki locally