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

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

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:

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.

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:

 


Send feedback on this topic to McObject.