Qore RestHandler Module Reference  1.2
RestHandler::RestHandler Class Reference

this is the main handler class to be registered with the HttpServer More...

Inheritance diagram for RestHandler::RestHandler:

Public Member Functions

 addClass (AbstractRestClass cls)
 adds a REST class to the handler
 
 constructor (*HttpServer::AbstractAuthenticator auth, RestSchemaValidator::AbstractRestSchemaValidator validator=new NullRestSchemaValidator())
 create the object optionally with the given HttpServer::AbstractAuthenticator More...
 
hash get (hash cx, *hash ah)
 default get handler
 
auto handleExternalRequest (string method, string path, *hash body, hash cx={})
 processes REST API calls outside the HTTP server More...
 
hash< HttpResponseInfo > handleRequest (HttpListenerInterface listener, Socket s, hash cx, hash hdr, *data b)
 called by the HTTP server to handle incoming HTTP requests More...
 
 logDebug (string fmt)
 default implementation is empty; this method is called with debug log messages; reimplement in subclasses to provide for logging
 
 logError (string fmt)
 default implementation is empty; this method is called with error log messages; reimplement in subclasses to provide for logging
 
 logInfo (string fmt)
 default implementation is empty; this method is called with informational log messages; reimplement in subclasses to provide for logging
 
string name ()
 returns the name of the root REST class
 
 removeRootPath (reference< string > path)
 default implementation is empty
 
 requestDeserializationError (hash hdr, hash cx, string body)
 default implementation is empty
 
 responseSerializationError (hash cx, *hash aih, hash rv)
 default implementation is empty
 
- Public Member Functions inherited from RestHandler::AbstractRestClass
hash< HttpServer::HttpHandlerResponseInfohandleRequest (HttpListenerInterface listener, RestHandler rh, Socket s, *list cl, string mn, hash cx, *hash args)
 this method is called by the RestHandler class to match the right object with incoming requests
 
*AbstractRestClass subClass (string name, hash cx, *hash args)
 this method will be called to find a sub-class (ie with GET /invoices/1 - if this class represents "invoices", then subClass("1") will be called to return invoice 1; return NOTHING if the object doesn't exist More...
 

Static Public Member Functions

static hash makeResponse (int code, auto body, *hash hdr)
 creates a hash for an HTTP response with the response code and a literal response message body
 

Public Attributes

const Err501
 a hash for a 501 Unimplemented error message
 
const Methods
 supported HTTP methods
 
const MimeDataTypes
 supported mime types for de/serializing responses
 

Private Member Functions

Mutex mx ()
 mutex lock
 

Private Attributes

hash ch
 class hash: name -> AbstractRestClass
 
RestSchemaValidator::AbstractRestSchemaValidator validator
 REST schema validator.
 

Detailed Description

this is the main handler class to be registered with the HttpServer

The RestHandler class should be subclassed to customize its behavior.

To provide for logging; the following methods can be reimplemented in subclasses:

In order to match REST requests under a root path, reimplement the following method in a subclass:

Member Function Documentation

◆ constructor()

RestHandler::RestHandler::constructor ( *HttpServer::AbstractAuthenticator  auth,
RestSchemaValidator::AbstractRestSchemaValidator  validator = new NullRestSchemaValidator() 
)

create the object optionally with the given HttpServer::AbstractAuthenticator

Parameters
auththe authentication object to use to authenticate connections (see HttpServer::AbstractAuthenticator); if no HttpServer::AbstractAuthenticator object is passed, then by default no authentication will be required
validatora REST API schema validator object; if none is present, then the default REST de/serialization support is provided as documented in RestSchemaValidator::NullRestSchemaValidator

◆ handleExternalRequest()

auto RestHandler::RestHandler::handleExternalRequest ( string  method,
string  path,
*hash  body,
hash  cx = {} 
)

processes REST API calls outside the HTTP server

Requests will be dispatched to REST classes registered with this object

Parameters
methodthe HTTP method; if the the method is unknown, an UNKNOWN-REST-METHOD exception is raised
paththe URI path for the call
bodythe arguments to the call; note that arguments are combined with any arguments provided in path
cxsimulated HTTP call context hash
Returns
the response value of the REST method
Exceptions
UNKNOWN-REST-METHODthe HTTP method is unknown / unsupported
INVALID-URI-PATHURI cannot be parsed
INVALID-REST-ARGSinvalid REST action
REST-CLASS-ERRORinvalid / unknown REST class in URI path
REST-ERRORan error response was returned from the REST handler for the given method
Note
  • the arg key of the exception hash in the exceptions above contains the HTTP status code of the response
  • exceptions thrown internally by REST handlers are returned directly; no 409 status code is added in the arg key of the exception hash
Since
RestHandler 1.2

◆ handleRequest()

hash<HttpResponseInfo> RestHandler::RestHandler::handleRequest ( HttpListenerInterface  listener,
Socket  s,
hash  cx,
hash  hdr,
*data  b 
)

called by the HTTP server to handle incoming HTTP requests

Requests will be dispatched to REST classes registered with this object

Parameters
listenera listener API object
sthe Socket object serving the request
cxcall context hash; this hash will have the following keys:
  • socket: the bind address used to bind the listener ("socket-info" provides more detailed information)
  • socket-info: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo())
  • peer-info: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo())
  • url: a hash of broken-down URL information (as returned from parse_url())
  • id: the unique HTTP connection ID
  • ssl: True if the request was encrypted with HTTPS, False if not
  • listener-id: the HTTP server listener ID (see HttpServer::HttpServer::getListenerInfo())
hdrincoming header hash; all keys will be converted to lower-case, additionally the following keys will be present:
  • method: the HTTP method received (ie "GET", "POST", etc)
  • path: the HTTP path given in the request, after processing by decode_url() (Qore function)
  • http_version: the HTTP version number in the request (either "1.0" or "1.1")
bmessage body, if any
Returns
a hash with the following keys:
  • "code": the HTTP return code (see HttpServer::HttpCodes)
  • "body": the message body to return in the response
  • "close": (optional) set this key to True if the connection should be unconditionally closed when the handler returns
  • "hdr": (optional) set this key to a hash of extra header information to be returned with the response