HSMOD.REST.Base

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.

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.

Domain used for localization.

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.

override this parameter to provide a default value for the argument "pAPIClassName" in SimpleRESTRequestResponse()

Enable CSP Sessions for REST

Convenience method for determining the current login Returns: 200 OK; Payload is the identity username

Convenience method for determining the current namespace Returns: 200 OK; Payload is the namespace

Convenience method for implementing _ping type routes Returns: 200 OK; Payload is the text "pong"

Convenience method for implementing _version Returns: 200 OK; Payload is the Ensemble system version

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.

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.

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.

Return value is a %Status value that will be used as the return value of SimpleRESTRequestResponse().

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:

1. log the %Status argument to the Ensemble event log
2. populate the %status.Response value with the provided HTTP response string value
3. 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.

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).

1. 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.
2. 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.
3. pRequestClassName: the name of the class we expect to find in the %request object. If omitted, we validate the class using the method signature.
4. pResponseClassName: the name of the expected response class. If omitted, we validate the class using the method signature.
5. pDisableMethodSignatureValidation: if set to 1, this turns off our validation of the method signature. Use at your own risk!
6. 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

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.