• NAME
• DESCRIPTION
  • Routing guidelines for the API controllers
• PUBLIC INTERFACE
  • RequestMethods()
  • RequestPath()
  • GetRequestMethods()
  • GetRequestPath()

NAME

Kernel::WebApp::Controller::Role::Routable - 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

All routes which directly relate to a frontend should go to /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).

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