<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.users" 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> Users - Manage Perforce users </title> <para> These methods allow you to list, edit, and maintain user 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.users.v1_users_GET"> <literal>GET /v1/users</literal> </link> </para> </entry> <entry> <para>List available users</para> </entry> </row> <row> <entry> <para> <link linkend="api.users.v1_users_POST"> <literal>POST /v1/users</literal> </link> </para> </entry> <entry> <para>Create a new user specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.users.v1_users_id_GET"> <literal>GET /v1/users/[user]</literal> </link> </para> </entry> <entry> <para>Describe a single user specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.users.v1_users_id_PATCH"> <literal>PATCH /v1/users/[user]</literal> </link> </para> </entry> <entry> <para>Update a user specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.users.v1_users_id_DELETE"> <literal>DELETE /v1/users/[user]</literal> </link> </para> </entry> <entry> <para>Delete a user specification</para> </entry> </row> </tbody> </tgroup> </informaltable> <section xml:id="api.users.v1_users_GET"> <title><literal>GET /v1/users</literal></title> <para> Lists available users in the system. </para> <para> The resources of this list are summaries of users in the system. For more details of each user, append the <literal>user</literal> property the end of this URL. </para> <para> There are no other parameters to this method. </para> <para> This method requires authentication. See <link linkend="userprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.users.v1_users_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag users</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_users.html"> <literal>p4 users</literal> command reference. </ulink>. </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>User</literal></entry> <entry>The user login and primary ID</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>FullName</literal></entry> <entry>The persons actual name, used for display</entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>Email</literal></entry> <entry>The user's email address, used by some applications.</entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The user type is typically <literal>standard</literal>, <literal>operator</literal>, or <literal>service</literal>. See <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_user.html"> the command reference </ulink> for more information. </entry> <entry>string</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.users.v1_users_GET.example"> <title>Example</title> <para>Our standard authenticated request format for listing users:</para> <programlisting> GET /v1/users HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Here's an example of a list with two users in the response: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [{ "User": "jdoe", "Update": 1412364334, "Access": 1412375184, "FullName": "John Doe", "Email": "jdoe@example.com", "Type": "standard", "Password": "enabled" }, { "User": "super", "Update": 1412364200, "Access": 1412375192, "FullName": "Super User", "Email": "super@example.com", "Type": "standard", "Password": "enabled" }]</programlisting> </simplesect> </section> <section xml:id="api.users.v1_users_POST"> <title><literal>POST /v1/users</literal></title> <para> Creates a new user specification. </para> <para> Upon success, this will return a 302 redirect to the new user specification resource that has been created. </para> <para> If the user already exists, this method will replace the existing user completely. </para> <para> This method requires authentication. See <link linkend="userprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.users.v1_users_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>User</literal></entry> <entry>The user's login</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>Either <literal>standard</literal>, <literal>operator</literal>, or <literal>service</literal></entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Email</literal></entry> <entry>The user's email address</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>FullName</literal></entry> <entry>The user's real name</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Password</literal></entry> <entry>The user's password</entry> <entry>string</entry> <entry>body</entry> <entry>Maybe, depends on server <literal>security</literal> level</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.users.v1_users_id_POST.example"> <title>Example</title> <para> Create a new user <literal>example</literal>, this defaults to creating a standard user. </para> <programlisting language="json"> POST /v1/users HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "User": "example", "Email": "example@example.com", "FullName": "Example User", "Password": "example1A" }</programlisting> <para> The return value should be a redirect to the details page of the new user. </para> <programlisting> HTTP/1.1 303 Found Location: http://example.com/p4/v1/users/example</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.users.v1_users_id_GET"> <title><literal>GET /v1/users/[user]</literal></title> <para> Return user details. </para> <para> This method requires authentication. See <link linkend="userprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.users.v1_users_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>user</entry> <entry>The user name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.users.v1_users_id_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag user</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_user.html"> <literal>p4 user</literal> command reference. </ulink>. </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>User</literal></entry> <entry>The login of the user</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>Typically <literal>standard</literal>, can be <literal>operator</literal>, or <literal>service</literal></entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Email</literal></entry> <entry>The user's email address</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>FullName</literal></entry> <entry>The user's real name</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Password</literal></entry> <entry>The user's password</entry> <entry>string</entry> <entry>body</entry> <entry>Maybe, depends on server <literal>security</literal> level</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.users.v1_users_id_GET.example"> <title>Example</title> <para> Here is an example request for the user <literal>jdoe</literal>. </para> <programlisting> GET /v1/users/jdoe 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 { "User": "jdoe", "Type": "standard", "Email": "jdoe@example.com", "Update": 1412364334, "Access": 1412375184, "FullName": "John Doe", "Password": "******", "AuthMethod": "perforce" }</programlisting> </simplesect> </section> <section xml:id="api.users.v1_users_id_PATCH"> <title><literal>PATCH /v1/users/[user]</literal></title> <para> Update user specifications. Only the specified parameters in the body will be changed. </para> <para> This method requires authentication. See <link linkend="userprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.users.v1_users_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>user</literal></entry> <entry>The name of the user</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>Typically <literal>standard</literal>, can be <literal>operator</literal>, or <literal>service</literal></entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry><literal>Email</literal></entry> <entry>The user's email address</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>FullName</literal></entry> <entry>The user's real name</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Password</literal></entry> <entry>The user's password</entry> <entry>string</entry> <entry>body</entry> <entry>Maybe, depends on server <literal>security</literal> level</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.users.v1_users_id_PATCH.example"> <title>Example</title> <para> Here we'll update the name of the existing user <literal>jdoe</literal>. </para> <programlisting language="json"> PATCH /v1/users/jdoe HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "FullName": "Johnny B. Doe" }</programlisting> <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.users.v1_users_id_DELETE"> <title><literal>DELETE /v1/users/[user]</literal></title> <para> Removes the user specification. </para> <para> This method requires authentication. See <link linkend="userprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.users.v1_users_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>user</literal></entry> <entry>The user name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.users.v1_users_id_DELETE.example"> <title>Example</title> <para> Delete the user <literal>new_user</literal> </para> <programlisting language="json"> DELETE /v1/users/new_user 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/users.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. |