internal package Foswiki::UI::Rest

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

internal package Foswiki::UI::Rest

UI delegate for REST interface

StaticMethod registerRESTHandler( $subject, $verb, \&fn, %options )

Adds a function to the dispatch table of the REST interface for a given subject. See CommandAndCGIScripts for more info.

• $subject - The subject under which the function will be registered.
• $verb - The verb under which the function will be registered.
• \&fn - Reference to the function.

The handler function must be of the form:

sub handler(\%session, $subject, $verb, $response) -> $text

where:

• \%session - a reference to the Foswiki session object (may be ignored)
• $subject - The invoked subject (may be ignored)
• $verb - The invoked verb (may be ignored)
• $response reference to the Foswiki::Response object that is used to compose a reply to the request

If the redirectto parameter is not present on the REST request, then the return value from the handler is used to determine the endpoint for the request. It can be:

• undef - causes the core to assume the handler handled the complete request i.e. the core will not generate any response to the request
• text - any other non-undef value will be written out as the content of an HTTP 200 response. Only the standard headers in the response are written.

Additional options are set in the %options hash. These options are important to ensuring that requests to your handler can't be used in cross-scripting attacks, or used for phishing.

• authenticate - use this boolean option to require authentication for the handler. If this is set, then an authenticated session must be in place or the REST call will be rejected with a 401 (Unauthorized) status code. By default, rest handlers do not require authentication.
• validate - use this boolean option to require validation of any requests made to this handler. By default, requests made to REST handlers are not validated.
• http_allow use this option to specify the HTTP methods that can be used to invoke the handler.