# 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
>         }
>       ]
>     }