<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.groups" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" > <title> Groups - List and manage group specifications </title> <para> These methods allow you to list, edit, and maintain group specifications in your Perforce server. </para> <informaltable> <tgroup cols="2"> <colspec colname="topic" colwidth="*"/> <colspec colname="description" colwidth="*"/> <thead> <row> <entry> <para>Path</para> </entry> <entry> <para>Description</para> </entry> </row> </thead> <tbody> <row> <entry> <para> <link linkend="api.groups.v1_groups_GET"> <literal>GET /v1/groups</literal> </link> </para> </entry> <entry> <para>List group assignments</para> </entry> </row> <row> <entry> <para> <link linkend="api.groups.v1_groups_POST"> <literal>POST /v1/groups</literal> </link> </para> </entry> <entry> <para>Create a new group specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.groups.v1_groups_id_GET"> <literal>GET /v1/groups/[group]</literal> </link> </para> </entry> <entry> <para>Describe a single group specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.groups.v1_groups_id_PATCH"> <literal>PATCH /v1/groups/[group]</literal> </link> </para> </entry> <entry> <para>Update a group specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.groups.v1_groups_id_DELETE"> <literal>DELETE /v1/groups/[group]</literal> </link> </para> </entry> <entry> <para>Delete a group specification</para> </entry> </row> </tbody> </tgroup> </informaltable> <section xml:id="api.groups.v1_groups_GET"> <title><literal>GET /v1/groups</literal></title> <para> Lists user assignments to all groups in the system. </para> <para> The resources of this list are users and groups in the system along with access associations for each user. </para> <para> There are no other parameters to this method. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.groups.v1_groups_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag groups</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_groups.html"> <literal>p4 groups</literal> command reference. </ulink>. </para> <para> By default the output of the <literal>p4 groups</literal> command is collated when the system wide configuration variable <literal>normalize_output</literal> is set to <literal>true</literal>. This makes this command truly appear as the 'collection' variation of <literal>GET /v1/groups/[group]</literal>, where the output of this command is nearly identical. If you do not set <literal>normalize_output</literal> to true, the output of this command is quite different; it is a list of users with different group properties set. </para> <informaltable> <tgroup cols="4"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry><literal>Group</literal></entry> <entry>The name of the group and primary ID</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>MaxResults</literal></entry> <entry> The maximum number of results that members of this group can access from the service from a single command. Not set by default. </entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>MaxScanRows</literal></entry> <entry>The maximum number of rows that members of this group can scan from the service from a single command. </entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>MaxLockTime</literal></entry> <entry> The maximum length of time (in milliseconds) that any one operation can lock any database table when scanning data. </entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>Timeout</literal></entry> <entry> The duration (in seconds) of the validity of a session ticket created by p4 login. The default value is 43,200 seconds (12 hours). To create a ticket that does not expire, set the <literal>Timeout</literal> field to <literal>unlimited</literal>. </entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>PasswordTimeout</literal></entry> <entry> The length of time (in seconds) for which passwords for users in this group remain valid. To disable password aging, use a value of unset. </entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>Owners</literal></entry> <entry>Array of users considered to be Owners of the group</entry> <entry>array</entry> <entry>No</entry> </row> <row> <entry><literal>Users</literal></entry> <entry>Array of Perforce logins considered to be normal users in the group.</entry> <entry>array</entry> <entry>No</entry> </row> <row> <entry><literal>Subgroups</literal></entry> <entry> Names of other Perforce groups. </entry> <entry> array </entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.groups.v1_groups_GET.example"> <title>Example</title> <para>Our standard authenticated request format for listing groups:</para> <programlisting> GET /v1/groups HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Here's an example of a list with the group <literal>the_group</literal> with three different user assignments. The user <literal>jdoe</literal> is an assigned owner, and the users <literal>kwalsh</literal> and <literal>zknox</literal> are just normal users. </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [{ "Group": "the_group", "MaxResults": "0", "MaxScanRows": "0", "MaxLockTime": "0", "Timeout": "43200", "PasswordTimeout": "0", "Owners": ["jdoe"], "Users": ["kwalsh", "zknox"] }]</programlisting> </simplesect> </section> <section xml:id="api.groups.v1_groups_POST"> <title><literal>POST /v1/groups</literal></title> <para> Creates a new group specification. </para> <para> Upon success, this will return a 303 redirect to the new group specification resource that has been created. </para> <para> If the group already exists, this method will replace the existing group completely. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.groups.v1_groups_POST.parameters"> <title>Parameters</title> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*" /> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry> <literal>Group</literal> </entry> <entry>The name of the group</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Owners</literal> </entry> <entry>Array of users considered to be Owners of the group </entry> <entry>array</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Users</literal> </entry> <entry>Array of Perforce logins considered to be normal users in the group. </entry> <entry>array</entry> <entry>body</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.groups.v1_groups_id_POST.example"> <title>Example</title> <para> We'll create a simple group <literal>something_new</literal>. </para> <programlisting language="json"> POST /v1/groups HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Group": "something_new", "Owners": ["zwalsh"], "Users": ["jdoe"] }</programlisting> <para> The return value should be a redirect to the details page of the new group. </para> <programlisting> HTTP/1.1 303 Found Location: http://example.com/p4/v1/groups/something_new</programlisting> <para> You may need to recall that the URL returned by a 303 response should be accessed via <literal>GET</literal>, and not via <literal>POST</literal>. </para> </simplesect> </section> <section xml:id="api.groups.v1_groups_id_GET"> <title><literal>GET /v1/groups/[group]</literal></title> <para> Return group details. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.groups.v1_groups_id_GET.parameters"> <title>Parameters</title> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry>group</entry> <entry>The group name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.groups.v1_groups_id_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag group</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_group.html"> <literal>p4 group</literal> command reference. </ulink>. </para> <para> Some fields may return values of <literal>"0"</literal> or <literal>"unset"</literal> to indicate they are not set. </para> <informaltable> <tgroup cols="4"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry><literal>Group</literal></entry> <entry>The name of the group and primary ID</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>MaxResults</literal></entry> <entry> The maximum number of results that members of this group can access from the service from a single command. Not set by default. </entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>MaxScanRows</literal></entry> <entry>The maximum number of rows that members of this group can scan from the service from a single command. </entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>MaxLockTime</literal></entry> <entry> The maximum length of time (in milliseconds) that any one operation can lock any database table when scanning data. </entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>Timeout</literal></entry> <entry> The duration (in seconds) of the validity of a session ticket created by p4 login. The default value is 43,200 seconds (12 hours). To create a ticket that does not expire, set the <literal>Timeout</literal> field to <literal>unlimited</literal>. </entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>PasswordTimeout</literal></entry> <entry> The length of time (in seconds) for which passwords for users in this group remain valid. To disable password aging, use a value of unset. </entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>Owners</literal></entry> <entry>Array of users considered to be Owners of the group</entry> <entry>array</entry> <entry>No</entry> </row> <row> <entry><literal>Users</literal></entry> <entry>Array of Perforce logins considered to be normal users in the group.</entry> <entry>array</entry> <entry>No</entry> </row> <row> <entry><literal>Subgroups</literal></entry> <entry> Names of other Perforce groups. </entry> <entry> array </entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.groups.v1_groups_id_GET.example"> <title>Example</title> <para> Here is an example request for the group <literal>group</literal>. This is a fairly simple group, containing only one view mapping. </para> <programlisting> GET /v1/groups/the_group HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> And the typical JSON response: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json { "Group": "the_group", "MaxResults": "0", "MaxScanRows": "0", "MaxLockTime": "0", "Timeout": "43200", "PasswordTimeout": "0", "Owners": ["jdoe"], "Users": ["kwalsh", "zknox"] }</programlisting> </simplesect> </section> <section xml:id="api.groups.v1_groups_id_PATCH"> <title><literal>PATCH /v1/groups/[group]</literal></title> <para> Update group specifications. Only the specified parameters in the body will be changed. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.groups.v1_groups_id_PATCH.parameters"> <title>Parameters</title> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*" /> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry> <literal>Group</literal> </entry> <entry>The name of the group</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Owners</literal> </entry> <entry>Array of users considered to be Owners of the group </entry> <entry>array</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Users</literal> </entry> <entry>Array of Perforce logins considered to be normal users in the group. </entry> <entry>array</entry> <entry>body</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.groups.v1_groups_id_PATCH.example"> <title>Example</title> <para> Here we'll update the owners of the existing group <literal >the_group</literal>. </para> <programlisting language="json"> PATCH /v1/groups/the_group HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Owners": ["zwalsh"] }</programlisting> <para> Note that this will replace the existing <literal>Owners</literal> array. </para> <para> The response will only contain the normal HTTP status information. </para> <programlisting> HTTP/1.1 200 OK</programlisting> </simplesect> </section> <section xml:id="api.groups.v1_groups_id_DELETE"> <title><literal>DELETE /v1/groups/[group]</literal></title> <para> Removes the group specification. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.groups.v1_groups_id_DELETE.parameters"> <title>Parameters</title> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry><literal>group</literal></entry> <entry>The group name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.groups.v1_groups_id_DELETE.example"> <title>Example</title> <para> Delete the group <literal>new_group</literal> </para> <programlisting language="json"> DELETE /v1/groups/new_group HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> The response will only contain the normal HTTP status information. </para> <programlisting> HTTP/1.1 200 OK</programlisting> </simplesect> </section> </chapter>
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#2 | 13972 | tjuricek |
Removing old microservice implementations. The system is now mostly a monolith. Eventually there will be a websocket service. |
||
#1 | 13458 | tjuricek |
Revising P4 Web API docbook documentation to become the Perforce Web Services guide. Right now this is just focused on the Qt SDK. The remaining protocol documentation, etc, will happen eventually. |
||
//guest/perforce_software/helix-web-services/main/p4_web_api/p4_web_api/docbook/xml/methods/groups.xml | |||||
#1 | 13412 | tjuricek |
Initial version of the web-services mainline. This is a collection of several projects, that will likely often get released together, though many of them may not always be relevant. See the README for more information. |