# eXtremeDB Web Services

> eXtremeDB provides Web Services using the popular REST (Representational State Transfer) protocol. The REST server can be accessed using any language that supports HTTP and JSON, which includes but is not limited to C/C++, Python, Java and C#. Note that the REST server is simply an HTTP server that serves JSON content, and thus conforms to the HTTP and JSON standards.

> The RESTful Web services support Basic HTTP authentication and encrypted communications using SSL. The Basic HTTP authentication mechanism implements the username and password authentication according to RFC 2617. As per the RFC, the username and the password are not encrypted, which means that this authentication method cannot be deemed secure when used without SSL (or an alternative encryption method).

> SSL for the RESTful Web services is implemented in a manner similar to the other networking components of eXtremeDB (for details see the Network Communications pages).

> # Overview

> eXtremeDB implements the ​RESTful web services to publish internal state and other information including

> - database statistics,
> - schema definition,
> - performance metrics,
> - database content (available soon).

> The eXtremeDB REST API is enabled in one of the following ways:

> - via xSQL configuration parameters if the database is started by xSQL, or
> - if the database is embedded in an application, the `mcorest` library provides REST C API functions using the `mcoews` embedded web service library.

> > Note that eXtremeDB supports nested data types of arbitrary depth, e.g. a class may contain a structure, which may contain an array of other structures, which, in turn, may contain other fields, etc. However, RESTful API methods that implement individual array, sequence, or structure element access are only available for the top-level fields (i.e. the fields of the classes). Additionally, it is possible to access the individual fields of structures contained by the top-level objects using the `api/db/<dbname>/classes/<struct_no>/byindex/<index_no>/eq/<key>/field/<field_no>/at/<elem_index>` resource.

> The C API implemented in the `mcorest` library is described in page Web Services C API Reference. The following section demonstrates how xSQL can be used to expose the REST server.

> ## xSQL REST API Demonstration

> To start the REST server from xSQL, create a configuration file `xsql.cfg` like the following in directory `eXtremeDB/target/bin`:

>         database_name : xsqldb,
>         database_size : 100m,

>         rest : {
>             addr : 127.0.0.1,
>             port : 8083
>         }

> Note that the IP address parameter `addr` is explicitly set to the localhost loop back address `127.0.0.1` for demonstration purposes. If omitted, this parameter defaults to `0.0.0.0` which allows the REST server to accept incoming connections on all available network interfaces (LAN, WiFi, whatever is installed). Be aware that this default behavior can be undesirable or even dangerous. To restrict network access any valid IP address may be specified; for example "`addr : 192.168.0.5`".

> Using this configuration file, you could start xSQL and request a REST resource on a Unix-Linux system with the commands like the following:

>         ~/mcobject/eXtremeDB_8.0$ ./eXtremeDB/target/bin/xsql -c xsql.cfg &
>         [1] 11721
>         ~/mcobject/eXtremeDB_8.0$ NOTICE:  Starting XSQL
>         NOTICE:  xsql started
>         NOTICE:  mcorest started at port 8083
>         Ctrl-C to stop SQL server

>         ~/mcobject/eXtremeDB_8.0$ curl http://localhost:8083/api/db
>         {
>             "databases":
>             [
>                 "xsqldb",
>                 "eXDB_perf"
>             ]
>         }

> Or on a Windows system, launch xSQL with the following command from directory `eXtremeDB/target/bin`:

>         xsql -c xsql.cfg
>         NOTICE:  Starting XSQL
>         NOTICE:  xsql started
>         NOTICE:  mcorest started at port 8083

>         press Enter to stop SQL server

> Now type the URL `http://localhost:8083/api/db` into your browser which will then display the following resource:

>         {
>             "databases":
>             [
>                 "xsqldb"
>             ]
>         }

> The ``db`` resource simply lists the names of the available databases in JSON format. Please see page eXtremeDB Web Service Resources for descriptions of the resources provided by the REST server.

> # Using the mcorest Library API

> The `mcorest` library can be used either in manual or in automatic multithreaded mode. The latter is easier to configure, since the `mcorest` library manages the interfaces and connections internally. However, there are circumstances when the single-threaded model is required, or a higher degree of control over the API is preferred; manual mode should be used in these cases. Both modes are described below. This description is intended to give an overview of the library.

> ## Initialization

> The `mcorest` library is initialized by calling `mcorest_initialize()` before any other `mcorest` function calls. Next, the application creates a `mcorest` server instance by calling `mcorest_create()`.The application receives the handle of the server through the `mcorest_h *rest` output parameter. One server instance should be created for each database served.

> The application then calls `mcorest_add_interface()` to tell the REST server which address(es) and port(s) to listen on. Multiple interfaces can be specified with consecutive calls to this function.

> If the application wishes to use the provided web services database, perf and SQL, then it must call the corresponding functions (`mcorest_svc_db_init()`, `mcorest_svc_perf_init()`, or `mcorest_svc_sql_init()`) to explicitly initialize the services.

> ## Basic HTTP authentication

> To enable the Basic HTTP authentication, use the mcorest_set_basic_auth() C API function. When using xSQL, set the http_realm, http_username, and http_password parameters of the rest section.

> To enable SSL, pass a pointer to the SSL parameters structure to the mcorest_add_interface() C API function. When using xSQL, set either the global settings in the global ssl_params section, or the REST-specific settings in the ssl_params subsection of the rest section.

> ## Execution

> As mentioned above, the server can run in automatic multithreaded mode. Alternatively, the application may drive its execution manually. Both modes are discussed below.

> ### Automatic multithreaded mode

> To start the server, the application calls `mcorest_start()`. The application is not allowed to call any of the `mcorest_*()` methods while the server is running in automatic mode, except for `mcorest_stop()` which is called when the application needs to stop the REST server (e.g. upon shutdown).

> ### Manual mode

> This mode may be preferred by the applications that need a finer degree of control over the web server. It is also the only choice when multithreading is not available on the target platform.

> In a single-threaded environment, the application would typically incorporate the following steps into its run loop, wherever convenient:

> - Call function `mcorest_interface_check()` to wait for and accept new connections. (Pass 0 to poll the interface without blocking.) If a new connection is accepted, this call returns `MCO_S_REST_CONN_ACCEPTED` and passes the connection handle to the caller through the `mcorest_conn_h *conn` argument. The application should store this handle until the connection is finished or cancelled.
> - Call function `mcorest_conn_execute()` for some or all active connections to let them exchange data with their peers. If the connection is executed normally and closed, this function returns the `MCO_S_REST_CONN_FINISHED` status code. Alternatively, if the connection is still alive, `MCO_S_OK` code is returned. The application may choose to close the active connections it doesn't need using function `mcorest_conn_cancel()`.

> When the application does not need the REST server anymore, it should cancel all active connections using function `mcorest_conn_cancel()` .

> In multithreaded mode, care should be taken to avoid sharing the REST server instance, interfaces and connections between threads.

> ### Numeric values as strings

> The RESTful Web Services' clients may request numeric values to be transmitted as strings in all JSON requests and responses by sending the `X-Numeric-Format: string` header with the HTTP requests. The server does not attempt to remember this setting; the header has to be sent with every request that requires this behavior. Furthermore, it is allowed to intermix requests with and without this setting.

> ## Deinitialization

> All interfaces must be closed by calling `mcorest_interface_close()` and the REST server(s) destroyed by calling `mcorest_destroy()`. Finally, the `mcorest` runtime should be shut down by calling ``mcorest_shutdown()``.

> ## Examples

> The following SDK Samples directories provide examples of Web Service C API usage:

> - `eXtremeDB/samples/native/core/24-rest/singlethreaded`
> - `eXtremeDB/samples/native/core/24-rest/multithreaded`