Kernel::WebApp::Controller::API::Base

NAME

Kernel::WebApp::Controller::API::Base – Base class for all API endpoints.

PUBLIC INTERFACE

Provides a 4-phase request handling architecture.

Handler()

implements a 4-phase request handling. Endpoints should not override "Handler()", but can provide their own implementation of these 4 phase methods:

"Authenticate()"
"DataValidate()"
"Authorize()"
"Action()"

The "Handler()" method will execute the 4 phases in this order. If any of these create a response (e. g. 401 Unauthenticated) or return a false value, the processing is stopped.

This methods also sends the API version information in the custom X-OTRS-API-Version HTTP header for all controllers consuming this role, if requested via X-OTRS-API-Debug header.

Authenticate()

checks if the user has the needed credentials (e. g., a customer access token).

Default implementation is a no-op, can be overridden by endpoints or roles.

Custom handlers should return a 401 Unauthorized response in case of failed authentication.

RenderAuthenticationError()

generates a error response for authentication errors, generates a 401 Unauthorized response (note that this HTTP status code name is not fully correct, because the error is about authentication).

    return $Self->RenderAuthenticationError(
        Data   => {}                # Optional, payload to send to the client
    );

DataValidate()

checks if the data payload is valid (e. g. a form was correctly filled).

Default implementation is a no-op, can be overridden by endpoints or roles.

Custom handlers should return a 422 Unprocessable Entity response in case of failed data validation. For data that is also used in the "Authorize()" phase, a 403 Forbidden response should be returned without detail information about the failed fields (to prevent information disclosure).

RenderDataValidationError()

generates a error response for input validation errors. Defaults to 422 Unprocessable Entity, but this can be changed.

    return $Self->RenderDataValidationError(
        Data   => {                 # Optional, payload to send to the client
            Errors => {             # An "Errors" key with detail information for the failed keys is recommended.
                Field1 => {}
            },
            OtherInformation => ...,
        }
        Status => 413,              # Optional, defaults to 422 (example: Payload too large)
    );

RenderNotFoundError()

special case (404 Not Found) for input validation errors.

    return $Self->RenderNotFoundError(
        Data   => {},               # Optional, payload to send to the client
    );

Authorize()

checks if the authenticated user has the necessary permission for the requested resource(s).

Default implementation is a no-op, can be overridden by endpoints or roles.

Custom handlers should return a 403 Forbidden response in case of failed authorization (e.g., no permission to access to a ticket).

RenderAuthorizationError()

generates a error response for authorization errors, generates a 403 Forbidden response.

    return $Self->RenderAuthorizationError(
        Data   => {}                # Optional, payload to send to the client
    );

Action()

after all previous checks succeeded, this method will perform the requested action (e. g. create or fetch a ticket).

Default implementation is a no-op, can be overridden by endpoints or roles.

CustomErrorResponses()

provides a hash of custom error responses that the controller can generate. Endpoints should override this like follows:

    sub CustomErrorResponses {
        return {
            'MultipleAccountsFound' => {
                ErrorMessage => Translatable('Multiple accounts with the same email address were found. Please contact the administrator.'),
            },
            'EmailSendingFailed' => {
                ErrorMessage => Translatable('Could not send password recovery instructions via email. Please contact the administrator.'),
            },
            'CustomErrorWithParameters' => {
                ErrorMessage => Translatable('Custom errors can have placeholders: %s.')
            },
        };
    }

This information is used both to generate the API documentation and also to generate the actual error responses, see "RenderCustomError()".

RenderCustomError()

generates a 900 Custom Error based on the defined custom errors (see "CustomErrorResponses()").

    return $Self->RenderCustomError(
        ErrorIdentifier => 'EmailSendingFailed',
    );

    return $Self->RenderCustomError(
        ErrorIdentifier => 'CustomErrorWithParameters',
        ErrorMessageParams => ['Value for the first parameter', ...]
    );

APIVersion()

API endpoints need to implement this method method to return a version number. This version number should be incremented on changes in the endpoints input or output data.

    sub APIVersion { return 1.0.0 }

EndpointContext()

Gets the EndpointContext of a controller if it is defined. Form endpoints can define an EndpointContext so that it is clear for which "Screen" this is used. This is especially needed for ACLs, where you can define on which Endpoint an ACL should be used.

Scroll to Top