# mcorest_api_handler_fn

Web service request handler routine.

### For an overview see page Web Services

### Prototype

      typedef MCO_RET (* mcorest_api_handler_fn)(void *ctx, mcoapi_request_h request,
                const char *path_suffix);

### Arguments

ctx | Context pointer, as specified by the `mcorest_api_register_service()` call
request | Request structure
path_suffix | Any remaining characters of the path: child path elements, query parameters, etc.

### Description

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 the `mcorest_api_json_*()` calls.
> - Return `MCO_S_OK` code.
> - If the handler fails at some point, it should return one of the `MCO_E_REST_*` error codes. If the HTTP request has not been answered yet (i.e. no data has been sent), the Web server will return HTTP status code 500 to the caller, as well as error details in JSON format. The web service may use the mcorest_api_failure() function to provide additional details to the client. If the handler routine sends data (e.g. HTTP status and headers) to the client and then returns an error code, the connection is aborted by the Web server. Any buffered data is discarded. Alternatively, the handler may opt to return the corresponding HTTP status to the client and write any associated information itself. It should return `MCO_S_OK` afterwards.

### Return Codes

MCO_S_OK = 0 | Success
MCO_E_REST_* | Any of the Web Services Error Codes