NAME

Kernel::WebApp::Controller::Role::IsRoutable – provide routing information for endpoints.

DESCRIPTION

Routing guidelines for the API controllers

Choose the right HTTP method

If data is just fetched, HTTP GET should be used. For adding and changing of entities, HTTP POST, for deleting HTTP DELETE should be used. For pre-flight checks (e.g., to check if a file is downloadable), HTTP HEAD can be used.

There might be use cases where a choice is not easily made, for example invoking a complex search. In such a case, the choice can depend on the needed parameters (see below). If only simple parameters are needed, HTTP GET might be a good fit, but in case of complex data that needs to be sent, HTTP POST could be used just as well.

Note that HTTP GET and HEAD messages can never have a body, as this is not supported by XHR.

Separate generic and frontend routes

In general, all routes which directly relate to a frontend should start with /api/frontend/$name. All other routes should be frontend-agnostic, and be placed in /api/customer, /api/public or /api/agent (indicating the type of use of the system).

To decide in which context a new endpoint should be located, you should answer the following questions:

/api/frontend/$name:

Do you need to use frontend specific settings, which can not be passed as a parameter to the endpoint? Normally all settings can be passed to the endpoint, unless they are permission related.

Is the functionality only relevant for a frontend and includes no "real" data? I.e. the organizer is frontend only and all endpoints which handle the functionality are located in the frontend namespace.

Is the endpoint a form schema endpoint?

Does the endpoint return frontend only specific settings?

Does the endpoint return a completely frontend related structure, like the auto complete search results?

/api/customer, /api/public or /api/agent:

Is the endpoint a CRUD endpoint for an existing entity (e.g. create ticket or update/fetch of ticket properties), which is saved in the database?

Can the endpoint be used in a generic way which is not specific to a frontend?

Does the endpoint return data which is not frontend specific and can be used in different places?

Does the endpoint need no frontend specific settings? Can all input information be passed via a request parameter?

Group routes by entity or topic

Routes belonging together should be grouped (e.g. /api/customer/ticket/* for all routes relating to tickets, while article endpoints would go to the article sub folder).

Identify the entity

Simple parameters needed to identify a single entity to fetch or modify should go into the path. This includes IDs or slugs, which are safe to use in a path (e. g. /api/customer/ticket/id/:TicketID, /api/frontend/external/custom-page/:Slug). Note that simple params cannot contain dots.

Parameters which are more complex (like ContentID, which contains dots) or refer to multiple entities (like search parameters) should be sent as query parameters for HTTP GET requests (e.g. /api/customer/ticket/:TicketID/article/:ArticleID/attachment?ContentID=$ContentIDEncoded), or JSON body fields for HTTP POST requests.

The same is true for parameters that are not needed to identify a single entity to fetch or modify.

Create new entities

HTTP POST requests to create new entities should go directly to the top level folder (e.g. /api/customer/ticket for creating a new ticket).

PUBLIC INTERFACE

RequestMethods()

Indicate the HTTP methods that this endpoint will respond to.

    my $Methods = $Self->RequestMethods();

Returns

    - an array with the supported http methods, empty
    indicates that all methods are supported.

RequestPath()

Indicate which is the endpoint for this controller.

    my $Path = $Self->RequestPath();

Returns

    - a string

GetRequestMethods()

Gets the request methods defined for the route, if none if defined, by default support any.

GetRequestPath()

Return the controller request paths/endpoints