<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.clients" 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> Clients - List and manage client specifications </title> <para> These methods allow you to list, edit, and maintain client 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.clients.v1_clients_GET"> <literal>GET /v1/clients</literal> </link> </para> </entry> <entry> <para>List available clients</para> </entry> </row> <row> <entry> <para> <link linkend="api.clients.v1_clients_POST"> <literal>POST /v1/clients</literal> </link> </para> </entry> <entry> <para>Create a new client specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.clients.v1_clients_id_GET"> <literal>GET /v1/clients/[client]</literal> </link> </para> </entry> <entry> <para>Describe a single client specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.clients.v1_clients_id_PATCH"> <literal>PATCH /v1/clients/[client]</literal> </link> </para> </entry> <entry> <para>Update a client specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.clients.v1_clients_id_DELETE"> <literal>DELETE /v1/clients/[client]</literal> </link> </para> </entry> <entry> <para>Delete a client specification</para> </entry> </row> </tbody> </tgroup> </informaltable> <section xml:id="api.clients.v1_clients_GET"> <title><literal>GET /v1/clients</literal></title> <para> Lists available clients in the system. </para> <para> The resources of this list are summaries of clients in the system. For more details of each client, append the <literal>client</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="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.clients.v1_clients_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag clients</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_clients.html"> <literal>p4 clients</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>Client</literal></entry> <entry>The client name and primary ID</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Owner</literal></entry> <entry>The Perforce login of the user that owns this client</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>The options of the client specification</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>SubmitOptions</literal></entry> <entry>The submission options of the client specification</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>LineEnd</literal></entry> <entry>How line endings should be treated</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Root</literal></entry> <entry>The root directory on the user's machine</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Host</literal></entry> <entry>The host name the client should run on</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>The client description</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Update</literal></entry> <entry>The timestamp the workspace specification was last modified.</entry> <entry>number</entry> <entry>Yes</entry> </row> <row> <entry><literal>Access</literal></entry> <entry>The timestamp the workspace was last used in any way.</entry> <entry>number</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.clients.v1_clients_GET.example"> <title>Example</title> <para>Our standard authenticated request format for listing clients:</para> <programlisting> GET /v1/clients HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Here's an example of a system that only has one client: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [{ "Update": 1416846894, "Access": 1416846894, "Owner": "jdoe", "Options": "allwrite noclobber nocompress unlocked nomodtime normdir", "SubmitOptions": "submitunchanged", "LineEnd": "local", "Root": "/Users/tristan/dev/p4_web_api_client/work/client/jdoe_mac", "Host": "", "Description": "Created by jdoe.\n", "Client": "jdoe_mac" }]</programlisting> </simplesect> </section> <section xml:id="api.clients.v1_clients_POST"> <title><literal>POST /v1/clients</literal></title> <para> Creates a new client specification. </para> <para> Upon success, this will return a 303 redirect to the new client specification resource that has been created. </para> <para> If the client already exists, this method will replace the existing client completely. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.clients.v1_clients_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>Client</literal></entry> <entry>The name of the client</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Owner</literal></entry> <entry>The Perforce login of the user that owns the client</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this client</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>The options of the client specification</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>SubmitOptions</literal></entry> <entry>The submission options of the client specification</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>LineEnd</literal></entry> <entry>How line endings should be treated</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Root</literal></entry> <entry>The root directory on the user's machine</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Host</literal></entry> <entry>The host name the client should run on</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>View</literal></entry> <entry>How different paths in the depot should relate to each other. Each string in the array contains a source and target end of the mapping. See <ulink url="http://www.perforce.com/perforce/doc.current/manuals/p4guide/chapter.codelines.html#d0e8198">the user guide</ulink> for more information. </entry> <entry>array</entry> <entry>body</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.clients.v1_clients_id_POST.example"> <title>Example</title> <para> We'll create a simple client <literal>my-project-main</literal> that maps <literal>//depot/main/my-project/...</literal> to <literal>//depot/dev/my-project/...</literal>. </para> <programlisting language="json"> POST /v1/clients HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Client": "new_client", "Root": "/tmp/dir.\n", "View": ["//depot/main/my-project/... //new_client/my-project/..."] }</programlisting> <para> The return value should be a redirect to the details page of the new client. </para> <programlisting> HTTP/1.1 303 Found Location: http://example.com/p4/v1/clients/new_client</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.clients.v1_clients_id_GET"> <title><literal>GET /v1/clients/[client]</literal></title> <para> Return client details. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.clients.v1_clients_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>client</entry> <entry>The client name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.clients.v1_clients_id_GET.response_data"> <title>Response Data</title> <para> Returns values similar to the output of the <literal>p4 -ztag client</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_client.html"> <literal>p4 client</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>Client</literal></entry> <entry>The name of the client</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Owner</literal></entry> <entry>The Perforce login of the user that owns the client</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this client</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>The options of the client specification</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>SubmitOptions</literal></entry> <entry>The submission options of the client specification</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>LineEnd</literal></entry> <entry>How line endings should be treated</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Root</literal></entry> <entry>The root directory on the user's machine</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Host</literal></entry> <entry>The host name the client should run on</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>View</literal></entry> <entry>How different paths in the depot should be included in the user's workspace. Each string in the array contains a source and target end of the mapping. See <ulink url="http://www.perforce.com/perforce/doc.current/manuals/p4guide/chapter.configuration.html#DB5-17566">the user guide</ulink> for more information. </entry> <entry>array</entry> <entry>Yes</entry> </row> <row> <entry><literal>Update</literal></entry> <entry>The timestamp the workspace specification was last modified.</entry> <entry>number</entry> <entry>Yes</entry> </row> <row> <entry><literal>Access</literal></entry> <entry>The timestamp the workspace was last used in any way.</entry> <entry>number</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.clients.v1_clients_id_GET.example"> <title>Example</title> <para> Here is an example request for the client <literal>jdoe_mac</literal>. This is a fairly simple client, containing only one view mapping. </para> <programlisting> GET /v1/clients/temp_client 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 { "Client": "jdoe_mac", "Update": 1416846894, "Access": 1416846894, "Owner": "jdoe", "Description": "Created by jdoe.\n", "Root": "/Users/tristan/dev/p4_web_api_client/work/client/jdoe_mac", "Options": "allwrite noclobber nocompress unlocked nomodtime normdir", "SubmitOptions": "submitunchanged", "LineEnd": "local", "View": ["//depot/... //jdoe_mac/..."] }</programlisting> </simplesect> </section> <section xml:id="api.clients.v1_clients_id_PATCH"> <title><literal>PATCH /v1/clients/[client]</literal></title> <para> Update client 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.clients.v1_clients_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>client</literal></entry> <entry>The name of the client</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> <row> <entry><literal>Owner</literal></entry> <entry>The Perforce login of the user that owns the client</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this client</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>The options of the client specification</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>SubmitOptions</literal></entry> <entry>The submission options of the client specification</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>LineEnd</literal></entry> <entry>How line endings should be treated</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Root</literal></entry> <entry>The root directory on the user's machine</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Host</literal></entry> <entry>The host name the client should run on</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>View</literal></entry> <entry>How different paths in the depot should relate to each other. Each string in the array contains a source and target end of the mapping. See <ulink url="http://www.perforce.com/perforce/doc.current/manuals/p4guide/chapter.configuration.html#DB5-17566">the user guide</ulink> for more information. </entry> <entry>array</entry> <entry>body</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.clients.v1_clients_id_PATCH.example"> <title>Example</title> <para> Here we'll update the description of the existing client <literal >new_client</literal>. </para> <programlisting language="json"> PATCH /v1/clients/new_client HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Description": "The updated new_client description.\n" }</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.clients.v1_clients_id_DELETE"> <title><literal>DELETE /v1/clients/[client]</literal></title> <para> Removes the client specification. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.clients.v1_clients_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>client</literal></entry> <entry>The client name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.clients.v1_clients_id_DELETE.example"> <title>Example</title> <para> Delete the client <literal>new_client</literal> </para> <programlisting language="json"> DELETE /v1/clients/new_client 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/clients.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. |