Inherited description: Specifies the default character set for the page. This can be overriden using the
<CSP:CONTENT CHARSET=> tag, or by setting the %response.CharSet property
in the OnPreHTTP() method. If this parameter is not specified, then
for the default charset is utf-8.
parameter CONTENTTYPEJSON = application/json;
parameter CONTENTTYPETEXT = text/plain;
parameter CONVERTINPUTSTREAM = 1;
Inherited description: Specifies if input %request.Content or %request.MimeData values are converted from their
original character set on input. By default (0) we do not modify these and receive them
as a binary stream which may need to be converted manually later. If 1 then if there
is a 'charset' value in the request Content-Type or mime section we will convert from this
charset when the input data is text based. For either json or xml data with no charset
this will convert from utf-8 or honor the BOM if one is present.
parameter CSRFTOKEN = X-CSRF-TOKEN;
parameter DOMAIN = HSMOD;
Domain used for localization.
parameter HTTPAUTHENTICATIONMECHANISM = None;
parameter HandleCorsRequest = 1;
This parameter influences the CORS support. The default is an empty string meaning 'not specified'.
If set to true (1) then CORS processing is ON. If set to false (0) then CORS processing is OFF.
If left unset "" then the decision to process CORS is delegated to the setting on the URL map route.
parameter JSONFORMATFLAGS = 2aelnos;
parameter REQUESTGROUP;
parameter SIMPLEAPICLASSNAME;
override this parameter to provide a default value for the argument "pAPIClassName" in SimpleRESTRequestResponse()
Convenience method for implementing _version
Returns: 200 OK; Payload is the Ensemble system version
classmethod CheckSinglePermission(pResource As %String, pPermission As %String, pReasonText As %String) as %Status
wrapper for checkPermissions(), for checking permissions for the current user against a single
resource and permission string (e.g. "W"). For multiple resources, use checkPermissions.
classmethod ExtractServerError(pTestStatus As %Status, Output pServerErrorContent As %String) as %Status
Given a %Library.Status value (the argument pStatus), this method looks through its contents to see whether are HTTP 500 internal
server error messages. If it finds one, it returns that error string; otherwise, the output
argument will be empty (undefined).
generates a guid and places it in the session data.
classmethod HandleRESTRequestResponseProblem(pAPIClassName As %Dictionary.Classname, pAPIMethodName As %String, pValidationError As %Status, pIntendedHTTPResponse As %String = ..#HTTP500INTERNALSERVERERROR) as %Status
Callback method that is called whenever a problem arises in the validation steps
of SimpleRESTRequestResponse(). It is passed a (custom) %Status code that indicates
what went wrong, as well as an HTTP response string that seems appropriate. We also pass in the
names of the specified API class and method, to provide context.
This method, or its overrides, must return a value for the helper method to use as its return value,
and also populate %response.Status.
Default implementation is to:
log the %Status argument to the Ensemble event log
populate the %status.Response value with the provided HTTP response string value
return $$$OK
Extensions may override this method to customize behavior, but if the override does not populate %status.Response
it will be populated with "500" (internal server error), and the helper method will return
the validation-generated status error value.
Called for a REST page in the event of a login being required, in the sense that the CSP server failed to
authenticate the user, and we need to notify them that they need to log in. This is really a "post-login-failure" callback.
may be overridden by subclasses. This method is called by OnPreDispatch() and must decide
whether to call VerifySession(), GenerateVisibleSessionToken() or neither (if no
verification is being enforced). The default behavior is to check HSMOD.REST.ApplicationConfig
for configuration information; if configuration info is found then we generate a session token in login
cases and verify it otherwise. If no configuration info is found then nothing is enforced and this method
quits. We do not use the pUrl argument (we use the request contents instead) but we pass it in
case overrides want it. pMethod is used for matching the login config cases.
called on every URL dispatch request. Default implementation is to call ManageSessionVerification(). If
a REST API overrides this method it should also ensure that session verification is addressed.
classmethod OutputServerErrorToJSON(pStatusToExamine As %Status, Output pServerErrorFound As %Boolean) as %Status
given a %Library.Status value (the argument pStatusToExamine,
this method calls ExtractServerError() to see whether it contains
any HTTP 500 internal server errors. If it finds one, it extracts that value and serializes it into
the current HTTP response as JSON content. It also outputs a boolean flag value to indicate whether
such an error was found.
simple boilerplate helper method for API methods that have a single JSON request object and return
a single JSON response object from a single worker method somewhere else. This allows REST classes to
implement endpoints with just a wrapper method that calls this method, which handles common validation
and REST handling (JSON read/write, and so on).
pAPIClassName: the name of the class containing the method we should call to do the work. If omitted, we use the
value of SIMPLEAPICLASSNAME instead. If both are empty, we assume it's the current class name.
pAPIMethodName: the name of the method in the "report class" we will call. Assumed to have a signature
consisting solely of the request object and an output argument for the response object, and to return a %Status.
pRequestClassName: the name of the class we expect to find in the %request object. If omitted, we validate
the class using the method signature.
pResponseClassName: the name of the expected response class. If omitted, we validate the class using the
method signature.
pDisableMethodSignatureValidation: if set to 1, this turns off our validation of the method signature. Use at your own risk!
pHandledValidationError: if a validation error occurred (either with the method signature or with one of the objects), the
relevant status code is returned here in case the caller code wants to interrogate it. Normally this is not necessary,
because we have already logged it and set the %response.Status accordingly, but it is provided here for transparency. Most
REST endpoint methods calling this helper method will not need to examine it, and can omit it from the call.
This method validates that the specified API class method exists and has the expected signature (one request object in,
one request object out). It also validates the request object as an instance of the expected request object type,
and likewise it validates the response object. If a problem is detected in this area, the method returns
a custom internal error code and sets the %response.Status to "400" or "500". Extension classes can also customize the
handling of validation errors by overriding HandleRESTRequestResponseProblem().
If an error occurred during the
call to the specified code API method, an error status will be returned and the %response.Status will be 500.
validates session cookie; returns $$$OK or a 401 error
classmethod checkPermissions(pPermissions As %List, pReasonText As %String) as %Status
Verify the current user has at least one of the specified permissions. Returns OK if true, otherwise an error status code naming
the reason the permissions were needed and the current user identity (given by $Username). The pPermissions argument
is assumed to be a $list of expressions of the form $lb(a,b) where "a" is the resource and "b" is the
required permission. For example: $lb($lb("%HS_UserAdmin_Resource_Users","W"),$lb("%HS_Module2_Resource_Whatever","W")),
Given a %Status object, assign an appropriate HTTP status into %response.Status. Also write a JSON representation of status errors to the current output device.
If the %Status object contains a $$$HTTPStatus... code, this is used to assign the corresponding HTTP status. Otherwise, certain Ensemble system errors
will be assigned a 400,404,502 or 503 status, and all other errors will be assigned a 500 Internal Server Error status.