eXtremeDB Web Services C API

The mcorest library exposes a REST-like interface. Please see page eXtremeDB Web Service Resources for a list of the resources that are currently supported, as well as samples of the JSON responses.

For an overview see page eXtremeDB Web Services

The core library mcorest implements the basic functionality (parsing and dispatching HTTP requests, formatting JSON, etc.) used by the web service libraries. Each web service library registers itself with the core library and makes its services available through one or more URL paths.

Applications that wish to expose certain web services will link with the core library, as well as web service libraries and their dependencies. The web service libraries are not interdependent (unless explicitly stated), and thus the applications can select only the ones they need. Note that the services must be initialized explicitly by the application through their respective mcocore_svc_*_init() functions.

Three web service libraries are implemented currently:

• mcorestdb: implements basic database-related functionality: listing databases and retrieving basic class statistics. Requires mcouda.
• mcorestsql: implements SQL-related functionality; currently only displays engine statistics and RSQL client information. Requires mcosql.
• mcorestperf: provides perfmon statistics. Requires mcoperf.

Creating new Web Services for mcorest

It is possible to create new web services using the mcorest API defined in the mcorestapi.h header file. A web service will:

• Choose a URL path to serve (e.g. /api/myservice).
• Implement the service as a C function ("handler routine"), whose signature has to match the mcorest_api_handler_fn type.
• Register the URL path and the handler routine with the mcorest core library using the mcorest_api_register_service() function.

The handler routine in a web service library will be called when the core library gets an HTTP request for the web service's registered path. Then, the handler will:

• Optionally parse the URL path's child elements and query parameters that are passed through the handler's path_suffix argument.
• Send status code using one of the mcorest_api_status_*() calls.
• If the status code is 200/OK, the handler will optionally send a JSON response using mcorest_api_json_write() methods.
• Return MCO_S_OK code.
• If the handler fails at some point, it should return one of the MCO_E_REST_* error codes. However, note that in this case the HTTP connection will be dropped without sending an HTTP response.

Necessary and Optional Libraries

C and C++ applications that wish to use the web services must link with the following libraries:

mcorest	The embedded Web Services REST API
mcoews	HTTP server implementation
mcosaltimer	Low-resolution and high-resolution timer implementations
mcosalsmp	Required for multithreading support

Applications that wish to expose an existing web service will link with its library, as well as its dependencies:

mcorestdb	The database Web Service; requires mcouda for UDA APIs
mcorestsql	The SQL Web Service; requires mcosql
mcorestperf	The perfmon Web Service; requires mcoperf

API Reference

The table below lists the Web Services C API functions:

mcorest_initialize()	Initializes the MCO REST server runtime
mcorest_svc_db_init()	Initializes the database web service library
mcorest_svc_perf_init()	Initializes the perfmon web service library
mcorest_svc_sql_init()	Initializes the SQL web service library
mcorest_create()	Creates the MCO REST server instance and stores its handle in the rest parameter
mcorest_add_interface()	Adds a network interface to the MCO REST server instance
mcorest_set_basic_auth()	Set Basic HTTP authentication parameters for the server instance
mcorest_reset_basic_auth()	Reset Basic HTTP authentication parameters and disables the authentication
mcorest_start()	Start the MCO REST server
mcorest_stop()	Stops the MCO REST server in threaded mode after it was started with mcorest_start()
mcorest_interface_check()	Checks the interface for incoming network connections
mcorest_conn_execute()	Executes one or more HTTP requests
mcorest_conn_cancel()	Close an active connection
mcorest_interface_close()	Shuts down the interface
mcorest_destroy()	Destroys the MCO REST server instance
mcorest_shutdown()	Shut down the MCO REST server runtime
mcorest_api_handler_fn()	Web service request handler routine
mcorest_api_failure()	Record details of a handler failure
mcorest_api_failure_clear()	Reset the previously set failure details associated with the HTTP request object
mcorest_api_stream_with_request()	Initialize a stream from an MCO EWS HTTP request
mcorest_api_request_from_stream()	Return the MCO EWS HTTP request request associated with the stream
mcorest_api_register_service()	Register the URL path and the handler routine with the mcorest core library
mcorest_api_status_*()	Send API status code to the web service caller
mcorest_api_json_read_*()	Functions that read JSON data
mcorest_api_json_write_*()	Functions that write JSON data