NSDb exposes HTTP and Websocket APIs to perform SQL statements and NSDb commands. HTTP APIs expose the same functionalities provided by CLI interface. Furthermore, WS APIs allow registering real-time queries on NSDb cluster. Every time a Bit fulfilling a query is written, it's published on the corresponding WebSocket.
HTTP APIs implement three main route categories:
- Query API, used to run historical select queries.
- Data API, used to perform insert statements.
- Command API, allowing commands execution e.g. display of databases, namespaces and metrics, drop statements.
All the above-mentioned Web APIs allow custom security authorization mechanism implementation. To define authorization logic, user must implement io.radicalbit.nsdb.security.http.NSDBAuthProvider trait defining authorization behaviour for the database, namespace and metric models.
Once the custom authorization provider is set up, its canonical class name must be added to NSDb conf file under the key nsdb.security.auth-provider-class.
By default an io.radicalbit.nsdb.security.http.EmptyAuthorization provider class is plugged in implementing no auth logic.
A secure connection can be set up making use of SSL/TLS protocol enabled in NSDb cluster configuration. To access a more detailed description see SSL/TLS Documentation.
Swagger documentation is also available for all the endpoints described in this document.
Allow data retrieval from NSDb according to a provided query.
URL : /query
Method : POST, GET
Auth required : Depending on security configuration
Permissions required : Read permission on metric, depending on security configuration
Data params
Provide db, namespace, metric and the query to be executed, and optionally from and to timestamp to filter the results.
Dynamic where conditions can be specified using filter definition.
Filter elements are combined through AND operator.
{
"db": "[string]",
"namespace": "[string]",
"metric": "[string]",
"queryString": "[string]",
"from": "[optional timestamp in epoch format]",
"to": "[optional timestamp in epoch format]",
"filters": "[optional array of Filter]"
}Filter object is defines as below:
{
"dimension": "[string]",
"value": "[string|numerical depending on dimension type]",
"operator" : "[string which value must me in [=, >, >=, <, <=, like]]"
}Data examples
From and To fields are optionals.
{
"db": "db",
"namespace": "namespace",
"metric": "people",
"queryString": "select * from people limit 100",
"filters": [{ "dimension": "dimName1",
"value" : "value",
"operator": "like" },
{ "dimension": "dimName2",
"value" : 1,
"operator": ">" }
]
}{
"db": "db",
"namespace": "namespace",
"metric": "people",
"queryString": "select * from people limit 100",
"from": 0,
"to": 100000
}{
"db": "db",
"namespace": "namespace",
"metric": "people",
"queryString": "select * from people limit 100",
"from": 0,
"to": 100000,
"filters": [{ "dimension": "dimName1",
"value" : "value",
"operator": "=" },
{ "dimension": "dimName2",
"value" : 1,
"operator": "=" }
]
}Condition : If the query provided is valid an array of records will be returned
Code : 200 OK
Content example
{
"records": [
{
"timestamp": 100000,
"value": 1,
"dimensions": {
"key": "Key1"
}
},
{
"timestamp": 100000,
"value": 2,
"dimensions": {
"key": "Key2"
}
}
]
}Condition : If query is invalid.
Code : 400 BAD REQUEST
Content : Error message
Condition : If metric does not exist
Code : 404 NOT FOUND
Condition : If a generic error occurs.
Code : 500 INTERNAL SERVER ERROR
Content : Error message
Adding a parsed = true parameter in the request body, the query response will be enriched with the tokenized query.
Data example
{
"db": "db",
"namespace": "namespace",
"metric": "metric",
"queryString": "select count(*) from metric",
"parsed": true
}The response will be a json array with records object as result and parsed for the tokenized query
{
"records": [{
"timestamp": 0,
"value": 1,
"dimensions": {},
"tags": {
"count(*)": 1
}
}],
"parsed" : {
"db" : "db",
"namespace" : "namespace",
"metric" : "metric",
"distinct" : false,
"fields" : {
"fields" : [ {
"name" : "*",
"aggregation" : "count"
} ]
}
}
}Check if a query is valid.
URL : /query/validate
Method : POST
Auth required : Depending on security configuration
Permissions required : Read permission on metric, depending on security configuration
Data params
Provide db, namespace, metric and the query to be validated.
{
"db": "[string]",
"namespace": "[string]",
"metric": "[string]",
"queryString": "[string]"
}Data examples
From and To fields are optionals.
{
"db": "db",
"namespace": "namespace",
"metric": "people",
"queryString": "select * from people limit 100"
}{
"db": "db",
"namespace": "namespace",
"metric": "people",
"queryString": "non valid query"
}Condition : If the query provided is valid an empty success response will be returned
Code : 200 OK
Condition : If query is invalid.
Code : 400 BAD REQUEST
Content : Error message
Condition : If metric does not exist
Code : 404 NOT FOUND
This API allows bit insertion into NSDb's metric. Bit description and metric information must be defined in request body.
URL : /data
Method : POST
Auth required : Depending on security configuration
Permissions required : Write permission on metric, depending on security configuration
Data params
Provide db, namespace, metric and the bit to be inserted.
{
"db": "[string]",
"namespace": "[string]",
"metric": "[string]",
"bit": {
"timestamp": "[epoch timestamp]",
"value": "[numeric value]",
"dimensions": {
"dim1" : "[numeric or string value]",
"dim2" : "[numeric or string value]"
}
}
}Data example
{
"db": "db",
"namespace": "namespace",
"metric": "metric",
"bit": {
"timestamp": 100000,
"value": 0.5,
"dimensions": {
"dim1" : 25,
"dim2" : "dim2"
}
}
}Condition : If the bit provided is valid a OK response will be returned
Code : 200 OK
Condition : If bit is invalid.
Code : 400 BAD REQUEST
Content : Error message
Condition : If a generic error occurs.
Code : 500 INTERNAL SERVER ERROR
Content : Error message
Commands APis map some functionalities already implemented in NSDb Command Line Interface. They consist in a set of statements aimed to retrieve information about namespace and metric structure and on the other hand to perform drop action on the latter.
Show databases command retrieve the list of databases.
URL : /commands/dbs
Method : GET
Auth required : Depending on security configuration
http://<host>:<port>/commands/dbs
Code: 200 OK
Content example
{
"dbs":
[
"db1",
"db2"
]
}Show namespaces command retrieve the list of namespaces belonging to the specified database.
URL : /commands/<database_name>/namespaces
Method : GET
Auth required : Depending on security configuration
Permissions required : Read permission on selected database, depending on security configuration
Data params: Provide database name in url
http://<host>:<port>/commands/database/namespaces
Condition: database in url path exists and user has authorization access to the latter
Code: 200 OK
Content example
{
"namespaces": [
"namespace_name1",
"namespace_name2"
]
}Condition : Server error
Code : 500 Internal Server Error
Content : Error message
Show metrics command retrieves the list of metrics belonging to the specified namespace.
URL : /commands/<database_name>/<namespace_name>/metrics
Method : GET
Auth required : Depending on security configuration.
Permissions required : Read permission on selected namespace, depending on security configuration.
Data params: Provide database name and namespace name in url.
Condition: database and namespace in url path exist and user has authorization access to the latter.
Code: 200 OK
Content example
{
"metrics": [
"metric_name1",
"metric_name2"
]
}Condition : Server error
Code : 500 Internal Server Error
Content : Error message
Describe metric command retrieves the schema descriptor and custom shard interval and retention (if present) of a specific metric.
URL : /commands/<database_name>/<namespace_name>/<metric_name>
Method : GET
Auth required : Depending on security configuration
Permissions required : Read permission on selected metric, depending on security configuration
Data params: Provide database, namespace and metric name in url
Condition: database,namespace and metric in url path exist and user has authorization access to the latter.
Code: 200 OK
Content example
{
"fields": [
{ "name" : "dimension_1",
"type" : "VARCHAR"
},
{ "name" : "dimension_2",
"type" : "INTEGER"
}
],
"metricInfo": {
"db": "database",
"namespace": "namespace",
"metric": "metric",
"shardInterval": 172800000,
"retention": 86400000
}
}Condition : Server error
Code : 500 Internal Server Error
Content : Error message
Condition : Metric not found
Code : 404 Not Found
Drop Namespace command drops selected namespace and all belonging metrics.
URL : /commands/<database_name>/<namespace_name>
Method : DELETE
Auth required : Depending on security configuration.
Permissions required : Write permission on selected namespace, depending on security configuration.
Data params: Provide database and namespace name in url.
Condition: database and namespace in url path exist and user has authorization access to the latter.
Code: 200 OK
Condition : Server error
Code : 500 Internal Server Error
Content : Error message
Drop Metric command drops selected metric, deleting schema and related data.
URL : /commands/<database_name>/<namespace_name>/<metric_name>
Method : DELETE
Auth required : Depending on security configuration.
Permissions required : Write permission on selected metric, depending on security configuration.
Data params: Provide database,namespace and metric name in url.
Condition: database, namespace, metric in url path exist and user has authorization access to the latter.
Code: 200 OK
Condition : Server error
Code : 500 Internal Server Error
Content : Error message