# 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