Begin handler
Purpose: Define a request handler.

begin-handler <request path> [ private | public ] \
    [ get-param ( <name> [ type <type> ] [ default-value <value> ] ) , ... ]

    <any code>
end-handler

begin-handler starts the implementation of a request handler for <request path> (see request), which is <any code> up to end-handler. <request path> is not quoted.

A <request path> is a path consisting of any number of path segments. A request path can have alphanumeric characters, hyphens and forward slashes, and can start only with a forward slash.

For example, a <request path> can be "/wine-items" or "/items/wine" etc. In general, it represents the nature of a request, such as an action on an object, a resource path handled by it etc. There is no specific way to interpret a request path, and you can construct it in a way that works for you.

The source ".rim" file name that implements a given begin-handler matches its path and name, fully or partially (see request). For example, <request path> of "/items/wine" might be implemented in  "items/wine.rim" file (meaning in file "wine.rim" in subdirectory "items").

Note that you can also use "%%" instead of either begin-handler or end-handler or both. A <request path> cannot be a C reserved word, such as for instance "main" or "typedef" etc.
Security of request calls
If "public" clause is used, then a handler can be called from an outside caller, be it a web browser, some web service, service call or command-line program.

If "private" clause is used, then a handler cannot be called from an outside caller; it can only be called from another handler by using call-handler statement.

If neither "public" nor "private" is used, then the default is "private". This default mechanism automatically guards direct execution by outside callers of all handlers not marked "public"; it provides automatic safety guard.

You can change this default behavior with "--public" option in rim, in which case the default is "public". This is useful if either all request handlers should be public, or if only a handful fixed ones are private.
Input parameters
"get-param" clause can be used to specify input parameters; the usage is the same as with standalone get-param statement (see for details). You can obtain some input parameters this way, none, or all of them. If a parameter is conditional, i.e. depending on the value of other parameter(s), you'd likely obtain it inside the handler implementation when such condition is satisfied. This clause can be used for more concise code and to semantically state which parameters should be obtained regardless of any conditions.

For instance:
begin-handler /my-handler get-param p1
    ...
end-handler

is the same as:
begin-handler /my-handler
    get-param p1
    ...
end-handler

Input and output parameters to request handlers
Read more at input-output-parameters.
Examples
The following begin-handler is implemented in file "items/wines/red-wine.rim":
begin-handler  /items/wines/red-wine public
    @This is a request handler to display a list of red wines!
end-handler

Another way to write this is:
%%  /items/wines/red-wine public
    @This is a request handler to display a list of red wines!
%%

See also
Service processing
after-handler  
before-handler  
begin-handler  
call-handler  
input-output-parameters  
See all
documentation

Copyright (c) 2019-2025 Gliim LLC. All contents on this web site is "AS IS" without warranties or guarantees of any kind.