The eXtremeDB Web Service Resources

The mcorest library exposes a REST-like interface to access a number of eXtremeDB resources. The response data is encoded using JSON notation.

For an overview see page eXtremeDB Web Services

In order to enable access to the eXtremeDB Web Services, the REST server must be started. When using xSQL to start the REST server, the rest section must appear in the configuration file. For example:

     
    database_name : xsqldb,
    database_size : 100m, 
     
    rest : {
        port : 8083
    }
     

(Note that here the rest parameter addr is omitted which allows the REST server to accept incoming connections on all available network interfaces. See page xSQL Web Services REST Parameters for further information.)

Below is a list of resources that are currently supported, as well as samples of the JSON responses. (For more detailed information use the links to the individual resource pages.)

/api	Lists the eXtremeDB version information and the registered web services	{ "version": { "major": 8, "minor": 0, "build": 1798, "revision": "unstable" }, "services": [ "\/api" "\/api\/xsql", "\/api\/db", "\/api\/perf", "\/api\/sql ] }
/api/db	Lists names of the available databases	{ "databases": [ "xsqldb", "eXDB_perf" ] }
/api/db/<dbname>/backup/status	The current status of a running incremental backup procedure	{ "phase": "IDLE", "max_passes": 0, "max_steps": 0, "pass_no": 0, "step_no": 0 }
/api/db/<dbname>/backup/control	Implements the asynchronous backup and restore control	{ "action": "backup_start", "file_name": "database.bkp", "label": "my_label", "backup_cycle_delay_msec": 1000 }
/api/db/<dbname>/backup/list	Prints the contents of a backup file	{ "backup_list": [ { "magic": 3987782336, "protocol_version": 2, "type": "SNAPSHOT", "flags": [ ], "backup_no": 0, "timestamp": 1558223122, "size": 411916, "offset": 0, "crc": 784321220, "trans_no": 10, "mem_page_size": 256, "disk_page_size": 0, "n_pages_total": 79003, "db_name": "bkpdb", "label": "BKPLBL00000" } ] }
/api/db/<dbname>/backup/verify	Verifies a backup file	{ "result": { "code": 0, "str": "MCO_S_OK - Operation succeeded" } }
/api/db/<dbname>/stat	Shows database statistics	{ "mem": { "free_pages": 406735", "total_pages": 406786, "page_size": 256 } "disk": { "data_file_size": 122880, "log_file_size": 73940, "used_database_size": 123648 }, "classes": [ { "table_name": "A", "objects_num": 3, "versions_num": 3, "core_pages": 3, "blob_pages": 0, "seq_pages": 0, "core_space": 768, "indexes": [ { "type": 2064, "type_s": [ "MCO_IDXST_TYPE_MEM", "MCO_IDXST_NATURE_BTREE", "MCO_IDXST_FEATURE_UNIQUE", "MCO_IDXST_FUNCTION_LIST" ], "plabel": "T.list_index_", "keys_num": 1, "pages_num": 1, "avg_cmp": 1, "max_cmp": 1, "btree": { "levels_num": 0, "duplicates_num": 0 } } ] } ], }
/api/db/<dbname>/classes	GET: Shows an abbreviated list of database classes	{ "classes": [ { "struct_no": 0, "name": "T", "class_code": 1 }, { "struct_no": 1, "name": "T2", "class_code": 2 } ], }
/api/db/<dbname>/structs	GET: Shows abbreviated list of database structures	{ "structs": [ { "struct_no": 0, "name": "B", "class_code": 1 } ], }
/api/db/<dbname>/schema	GET: Returns the entire schema of the database	{ "schema": { "classes": [ ... ], } { "structs": [ ... ], } }
/api/db/<dbname>/classes/<struct_no>	GET: Shows the schema of the database class identified by struct_no POST: Writes records to the database DELETE: Deletes all records of the specified class	{ "schema": { "struct_no": 0, "name": "T", "flags": 9, "flags_s": [ "MCO_DICT_SI_CLASS", "MCO_DICT_SI_LIST" ], "class_code": 1, "fields": [ ... ], "indexes": [ ... ], "events": [ ... ], } }
/api/db/<dbname>/structs/<struct_no>	GET: Shows the schema of the database structure identified by struct_no	{ "schema": { "struct_no": 0, "name": "B", "fields": [ "field_no": 0, "name": "i1", "type": 4, "type_s": "MCO_DD_INT1" ], ... } }
/api/db/<dbname>/classes/<struct_no>/byindex/<index_no>/list	GET: Returns records of the specified class using the index identified by index_no DELETE: Deletes individual objects, as specified by the query arguments	The response is a JSON object with two keys, header and resultset. The header contains the array of field descriptors, "fields". The format of the descriptors is the same as the one in the database schema (see /api/db/<dbname>/schema for details). The only difference is that structure fields' descriptors are recursively expanded, that is, every structure field descriptor will also include the array of that structure's fields' descriptors. The resultset is an array of JSON objects representing database records.
/api/db/<dbname>/classes/<struct_no>/byindex/<index_no>/eq/<key>	Supports GET, DELETE and PATCH requests	The response for GET requests is the same as for /api/db/<dbname>/classes/<struct_no>/byindex/<index_no>/list. DELETE removes individual records matching the specified key. PATCH updates individual fields of a record identified by the key value.
/api/db/<dbname>/classes/<struct_no>/byindex/<index_no>/eq/<key>/field/<field_no>/at/<elem_index	Supports GET, DELETE and PATCH requests	The response for GET requests returns the value of the element or structure field. DELETE deletes the element. PATCH overwrites the value of the element.
/api/db/<dbname>/classes/<struct_no>/byindex/<index_no>/eq/<key>/field/<field_no>/at/<elem_index>	Supports GET, DELETE and PATCH requests	Provides access to individual elements for arrays, vectors, sequences, and structures.
/api/perf	Shows perf database information, if enabled	{ "databases": [ { "name": "xsqldb", "no": 0 } ], "nodes": [ ], "readings": [ { "name": "MCO_PERF_ERROR_COUNT", "description": "Error count", "type": "counter", "no": 0 }, ... ] }
/api/sql/stat	Shows SQL statistics	{ "clients": [ { "clientid": 107173520884043, "statementid": 1, "connected": 1, "begin": 1514548415379034, "ip": "0:0:0:0:0:0:0:1", "port": 57480, "state": "DONE", "sql": "select * from Statistic", "failmsg": "", "memory": 70612, "rows": 0, "bytes": 176, "exectime": 776, "txtime": 51, "res_ucpu": 0, "res_scpu": 0, "res_inb": 0, "res_outb": 0, "res_maxrss": 0, "res_nswap": 0, "res_ncsw": 0 } ], "sql_engine": { "engine_heap_size": 724936, "total_heap_size": 0 } }
/api/sql/stat/sessions	Shows SQL sessions statistics and allow the http DELETE method for removing sessions from the history	{ "sessions": [ { "clientid": -1, "client_type": "interactive", "connected": 1, "begin_time": 1523278397728268, "end_time": 0, "idle_time": 2354789, "ip": "0:0:0:0:0:0:0:0", "port": 0, "memory": 0 "sql": "select * from Statistic", "failmsg": "", } ] }
/api/sql/exec	Execute an SQL statement or multiple statements	Request: { "sql": "SELECT * FROM Statistic", "max_records": 100, "max_array": 10, "max_sequence": 10 }   Response: { "type": "query", "data": { "header": { "resultset_size": 4, "fields": [ { "name": "i", "type": "Int4" }, { "name": "s", "type": "String" } ] }, "resultset": [ [ 1, "string1" ], [ 2, "string2" ], [ 3, "string3" ], [ 4, "string4" ] ] } }
/api/trace	Provide read-only trace access	{ "trace": "\/mcobject\/eXtremeDB_8.0\/eXtremeDB\/target\/xsql\/mcoxsql\/mcoxsql.cpp:2916-mcorest started at port 8083\n", "from": 5051, "to": 5151 }
/api/cluster/restlist	List the array of nodes in the cluster network	{ "cluster": [ { "node_id": 1, "role" : "node", "address": "127.0.0.1", "rest_iface": "0.0.0.0", "rest_port": 8081, "rest_secure: true } { "node_id": 2, "role" : "node", "address": "127.0.0.1", "rest_iface": "0.0.0.0", "rest_port": 8082, "rest_secure: true } ] }
/api/ha/restlist	List the array of nodes in the High Availability network	{ "ha": [ { "node_id": 1, "role" : "master", "address": "127.0.0.1", "rest_iface": "0.0.0.0", "rest_port": 8081, "rest_secure: true } { "node_id": 2, "role" : "replica", "address": "127.0.0.1", "rest_iface": "0.0.0.0", "rest_port": 8082, "rest_secure: true } ] }
/api/iot/restlist	List the array of nodes in the IoT network	{ "this_node_id": 1, "this_node_role": "server", "iot": [ { "node_id": 43, "role" : "device", "address": "127.0.0.1", "rest_iface": "0.0.0.0", "rest_port": 8082, "rest_secure: false } ] }