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 deletingHTTP 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
andHEAD
messages can never have a body, as this is not supported byXHR
. - 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 thearticle
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 forHTTP GET
requests (e.g./api/customer/ticket/:TicketID/article/:ArticleID/attachment?ContentID=$ContentIDEncoded
), orJSON
body fields forHTTP 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