Repository: incubator-guacamole-manual Updated Branches: refs/heads/master ed7bb81c5 -> 05aa0a57c
GUACAMOLE-289: Document declaration of REST resources within extensions. Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/commit/5f4e72e0 Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/5f4e72e0 Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/5f4e72e0 Branch: refs/heads/master Commit: 5f4e72e0e50141bcf23d75fdeb6eb34a3935012e Parents: a0d0497 Author: Michael Jumper <[email protected]> Authored: Sun May 21 19:26:26 2017 -0700 Committer: Michael Jumper <[email protected]> Committed: Sun May 21 19:49:00 2017 -0700 ---------------------------------------------------------------------- src/chapters/guacamole-ext.xml | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/5f4e72e0/src/chapters/guacamole-ext.xml ---------------------------------------------------------------------- diff --git a/src/chapters/guacamole-ext.xml b/src/chapters/guacamole-ext.xml index 415c026..4ed950c 100644 --- a/src/chapters/guacamole-ext.xml +++ b/src/chapters/guacamole-ext.xml @@ -556,6 +556,34 @@ <classname>Directory</classname> classes that automatically enforce the permissions associated with all objects and the associated user.</para> </section> + <section xml:id="ext-rest-resources"> + <title>REST resources</title> + <para>Arbitrary REST resources may be exposed by extensions at the + <classname>AuthenticationProvider</classname> level, if the resource does not + require an associated authenticated user, or at the <classname>UserContext</classname> + level, if the resource should be available to authenticated users only. In both cases, + the REST resource is provided through implementing the + <function>getResource()</function> function, returning an object which is annotated + with JAX-RS annotations (JSR 311).</para> + <para>The resource returned by <function>getResource()</function> functions as the root + resource, providing access to other resources beneath itself. The root resource for the + <classname>AuthenticationProvider</classname> is exposed at + <uri><replaceable>PATH</replaceable>/api/ext/<replaceable>IDENTIFIER</replaceable></uri>, + and the root resource for the <classname>UserContext</classname> is exposed at + <uri><replaceable>PATH</replaceable>/api/session/ext/<replaceable>IDENTIFIER</replaceable></uri>, + where <replaceable>PATH</replaceable> is the path to which Guacamole has been deployed + (typically <uri>/guacamole/</uri>) and <replaceable>IDENTIFIER</replaceable> is the + unique identifier for the <classname>AuthenticationProvider</classname>, as returned by + <function>getIdentifier()</function>.</para> + <para>The behavior of extension REST resources is generally left entirely to the + implementation, with the exception that the "token" request parameter is reserved for + use by Guacamole. This parameter contains the user's authentication token when the user + is logged in, and must be present on all requests which require authentication. Though + not relevant to REST resources exposed at the + <classname>AuthenticationProvider</classname> level, resources exposed at the + <classname>UserContext</classname> level inherently require the "token" parameter to + be present, as it is the sole means of locating the user's session.</para> + </section> <section xml:id="ext-permissions"> <title>Permissions</title> <para>The permissions system within guacamole-ext is an advisory system. It is the means by
