NAME

Kernel::WebApp::Controller::API::Role::ValidatesInputData – Role for API endpoints to validate input data.

PUBLIC INTERFACE

Provides methods to be defined in endpoints that are used to validate incoming data fields by URI parameters, query parameters and/or JSON body fields. The field validations will be performed via the data validation backend (see Kernel::System::DataValidation) for more information about how to use it, the different validators and it's possible parameters.

has ValidationUriParameters

Method that holds the validation definition for URI parameters. Endpoints can define it like this:

    sub ValidationUriParameters {
        return {
            Fields => {
                TicketID => [
                    'Required',
                    {
                        Validator => 'Pattern',     # regex pattern validation
                        Arguments => '^\d+$'
                    },
                    'Ticket::TicketID',             # deep validation
                ],
            },
            FieldsUsedForAuthorization => ['TicketID'],     # optional, indicates that this field is used for the Authentication phase
            Example => {
                TicketID => 123,                    # example parameter used for the endpoint documentation
            },
        };
    }

has ValidationQueryParameters

Method that holds the validation definition for query parameters. Endpoints can define it like this:

    sub ValidationQueryParameters {
        return {
            Fields => {
                TicketID => [
                    'Required',
                    {
                        Validator => 'Pattern',     # regex pattern validation
                        Arguments => '^\d+$'
                    },
                    'Ticket::TicketID',             # deep validation
                ],
            },
            FieldsUsedForAuthorization => ['TicketID'],     # optional, indicates that this field is used for the Authentication phase
            Example => {
                TicketID => 123,                    # example parameter used for the endpoint documentation
            },
        };
    }

has ValidationJSONBodyFields

Method that holds the validation definition for json fields. Endpoints can define it like this:

    sub ValidationJSONBodyFields {
        return {
            Fields => {
                TicketID => [
                    'Required',
                    {
                        Validator => 'Pattern',     # regex pattern validation
                        Arguments => '^\d+$'
                    },
                    'Ticket::TicketID',             # deep validation
                ],
            },
            FieldsUsedForAuthorization => ['TicketID'],     # optional, indicates that this field is used for the Authentication phase
            Example => {
                TicketID => 123,                    # example parameter used for the endpoint documentation
            },
        };
    }

around DataValidate

The /DataValidate() method will be called automatically via the API base class, please see Kernel::WebApp::Controller::API::Base for more information. This subroutine will be called automatically during the execution of /DataValidate(), to perform the configured validations on the given input data.

In case of any validation errors, the request process will be interrupted and a 422 Unprocessable Entity response is sent, with a JSON representation of the errors. For more information about the error structure, please see Kernel::System::DataValidation, Kernel::System::DataValidation::Error and Kernel::System::DataValidation::Errors.

In the case of fields that are relevant for the Authorization phase, no error details will be sent, but instead a 403 Forbidden response with an empty body, to prevent information disclosure.

If the validation proceeds successfully, the request process continues without interruption.