<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.depots" 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> Depots - List and manage depot specifications </title> <para> These methods allow you to list, edit, and maintain depot 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.depots.v1_depots_GET"> <literal>GET /v1/depots</literal> </link> </para> </entry> <entry> <para>List available depots</para> </entry> </row> <row> <entry> <para> <link linkend="api.depots.v1_depots_POST"> <literal>POST /v1/depots</literal> </link> </para> </entry> <entry> <para>Create a new depot specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.depots.v1_depots_id_GET"> <literal>GET /v1/depots/[depot]</literal> </link> </para> </entry> <entry> <para>Describe a single depot specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.depots.v1_depots_id_PATCH"> <literal>PATCH /v1/depots/[depot]</literal> </link> </para> </entry> <entry> <para>Update a depot specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.depots.v1_depots_id_DELETE"> <literal>DELETE /v1/depots/[depot]</literal> </link> </para> </entry> <entry> <para>Delete a depot specification</para> </entry> </row> </tbody> </tgroup> </informaltable> <section xml:id="api.depots.v1_depots_GET"> <title><literal>GET /v1/depots</literal></title> <para> Lists available depots in the system. </para> <para> The resources of this list are summaries of depots in the system. For more details of each depot, append the <literal>depot</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.depots.v1_depots_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag depots</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_depots.html"> <literal>p4 depots</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>Depot</literal></entry> <entry>The depot name and primary ID</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The type of the depot</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>Text description of the depot</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Map</literal></entry> <entry>The depot map</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Date</literal></entry> <entry>The timestamp the depot was created</entry> <entry>number</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.depots.v1_depots_GET.example"> <title>Example</title> <para>Our standard authenticated request format for listing depots:</para> <programlisting> GET /v1/depots HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Here's an example of a list with just the default depot in the response: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [{ "Depot": "depot", "Date": 1410468749, "Type": "local", "Map": "depot/...", "Description": "Default depot" }]</programlisting> </simplesect> </section> <section xml:id="api.depots.v1_depots_POST"> <title><literal>POST /v1/depots</literal></title> <para> Creates a new depot specification. </para> <para> Upon success, this will return a 303 redirect to the new depot specification resource that has been created. </para> <para> If the depot already exists, this method will replace the existing depot completely. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.depots.v1_depots_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>Depot</literal></entry> <entry>The name of the depot</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this depot</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The type of the depot</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Map</literal></entry> <entry>The depot map</entry> <entry>body</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.depots.v1_depots_id_POST.example"> <title>Example</title> <para> We'll create a simple depot <literal>stuff</literal>. </para> <programlisting language="json"> POST /v1/depots HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Depot": "stuff", "Type": "local", "Map": "stuff/..." }</programlisting> <para> The return value should be a redirect to the details page of the new depot. </para> <programlisting> HTTP/1.1 303 Found Location: http://example.com/p4/v1/depots/stuff</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.depots.v1_depots_id_GET"> <title><literal>GET /v1/depots/[depot]</literal></title> <para> Return depot details. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.depots.v1_depots_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>depot</entry> <entry>The depot name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.depots.v1_depots_id_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag depot</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_depot.html"> <literal>p4 depot</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>Depot</literal></entry> <entry>The name of the depot</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this depot</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The type of the depot</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Map</literal></entry> <entry>The depot map</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Date</literal></entry> <entry>The timestamp the depot was created</entry> <entry>number</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.depots.v1_depots_id_GET.example"> <title>Example</title> <para> Here is an example request for the depot <literal>depot</literal>. This is a fairly simple depot, containing only one view mapping. </para> <programlisting> GET /v1/depots/depot 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 { "Depot": "depot", "Date": 1410468749, "Type": "local", "Map": "depot/...", "Description": "Default depot" }</programlisting> </simplesect> </section> <section xml:id="api.depots.v1_depots_id_PATCH"> <title><literal>PATCH /v1/depots/[depot]</literal></title> <para> Update depot 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.depots.v1_depots_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>depot</literal></entry> <entry>The name of the depot</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this depot</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The type of the depot</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Map</literal></entry> <entry>The depot map</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.depots.v1_depots_id_PATCH.example"> <title>Example</title> <para> Here we'll update the description of the existing depot <literal >new_depot</literal>. </para> <programlisting language="json"> PATCH /v1/depots/new_depot HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Description": "The updated new_depot 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.depots.v1_depots_id_DELETE"> <title><literal>DELETE /v1/depots/[depot]</literal></title> <para> Removes the depot specification. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.depots.v1_depots_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>depot</literal></entry> <entry>The depot name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.depots.v1_depots_id_DELETE.example"> <title>Example</title> <para> Delete the depot <literal>new_depot</literal> </para> <programlisting language="json"> DELETE /v1/depots/new_depot 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/depots.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. |