<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.branches" 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> Branches - List and manage branch specifications </title> <para> These methods allow you to list, edit, and maintain branch 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.branches.v1_branches_GET"> <literal>GET /v1/branches</literal> </link> </para> </entry> <entry> <para>List available branches</para> </entry> </row> <row> <entry> <para> <link linkend="api.branches.v1_branches_POST"> <literal>POST /v1/branches</literal> </link> </para> </entry> <entry> <para>Create a new branch specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.branches.v1_branches_id_GET"> <literal>GET /v1/branches/[branch]</literal> </link> </para> </entry> <entry> <para>Describe a single branch specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.branches.v1_branches_id_PATCH"> <literal>PATCH /v1/branches/[branch]</literal> </link> </para> </entry> <entry> <para>Update a branch specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.branches.v1_branches_id_DELETE"> <literal>DELETE /v1/branches/[branch]</literal> </link> </para> </entry> <entry> <para>Delete a branch specification</para> </entry> </row> </tbody> </tgroup> </informaltable> <section xml:id="api.branches.v1_branches_GET"> <title><literal>GET /v1/branches</literal></title> <para> Lists available branches in the system. </para> <para> The resources of this list are summaries of branches in the system. For more details of each branch, append the <literal>branch</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.branches.v1_branches_GET.response_data"> <title>Response Data</title> <para> Returns the result of the <literal>p4 -ztag branches</literal> command. For more field information refer to the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_branch.html">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>Branch</literal></entry> <entry>The branch 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 branch</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>The options of the branch specification</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>The branch description</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Update</literal></entry> <entry>The date the branch mapping was last changed.</entry> <entry>number</entry> <entry>Yes</entry> </row> <row> <entry><literal>Access</literal></entry> <entry>The date the branch mapping was last accessed.</entry> <entry>number</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.branches.v1_branches_GET.example"> <title>Example</title> <para>Our standard authenticated request format for listing branches:</para> <programlisting> GET /v1/branches HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Here's an example of a list with two branches in the response: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [{ "Branch": "yagg-main", "Update": 1410907712, "Access": 1410907712, "Owner": "super", "Options": "unlocked", "Description": "Maintains a path from a development area to a main area.\n" }, { "Branch": "secondary-dev", "Update": 1410907541, "Access": 1410907111, "Owner": "jdoe", "Options": "unlocked", "Description": "Updates project Secondary's development area.\n" }]</programlisting> </simplesect> </section> <section xml:id="api.branches.v1_branches_POST"> <title><literal>POST /v1/branches</literal></title> <para> Creates a new branch specification. </para> <para> Upon success, this will return a 303 redirect to the new branch specification resource that has been created. </para> <para> If the branch already exists, this method will replace the existing branch completely. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.branches.v1_branches_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>Branch</literal></entry> <entry>The name of the branch</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 branch</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this branch</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.branches.v1_branches_id_POST.example"> <title>Example</title> <para> We'll create a simple branch <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/branches HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Branch": "my-project-main", "Description": "Branch my project from main to dev.\n", "View": ["//depot/main/my-project/... //depot/dev/my-project/..."] }</programlisting> <para> The return value should be a redirect to the details page of the new branch. </para> <programlisting> HTTP/1.1 303 Found Location: http://example.com/p4/v1/branches/my-project-main</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.branches.v1_branches_id_GET"> <title><literal>GET /v1/branches/[branch]</literal></title> <para> Return branch details. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.branches.v1_branches_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><literal>branch</literal></entry> <entry>The branch name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.branches.v1_branches_id_GET.response_data"> <title>Response Data</title> <para> Returns the result of <literal>p4 -ztag branch [branch name]</literal>. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_branch.html" >command reference</ulink>. The main difference between the details and list view is the inclusion of the <literal>View</literal> field. </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>Branch</literal></entry> <entry>The name of the branch</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Owner</literal></entry> <entry>The Perforce login of the user that owns the branch</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this branch</entry> <entry>string</entry> <entry>Yes</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>Yes</entry> </row> <row> <entry><literal>Update</literal></entry> <entry>The date the branch mapping was last changed.</entry> <entry>number</entry> <entry>Yes</entry> </row> <row> <entry><literal>Access</literal></entry> <entry>The date the branch mapping was last accessed.</entry> <entry>number</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.branches.v1_branches_id_GET.example"> <title>Example</title> <para> Here is an example request for the branch <literal>yagg-main</literal>. This is a fairly simple branch, containing only one view mapping. </para> <programlisting> GET /v1/branches/yagg-main 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 { "Branch": "yagg-main", "Update": 1410907712, "Access": 1410907712, "Owner": "super", "Description": "Maintains a path from a development area to a main area.\n", "Options": "unlocked", "View": ["//depot/yagg/... //depot/main/yagg/..."] }</programlisting> </simplesect> </section> <section xml:id="api.branches.v1_branches_id_PATCH"> <title><literal>PATCH /v1/branches/[branch]</literal></title> <para> Update branch 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.branches.v1_branches_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>branch</literal></entry> <entry>The name of the branch</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 branch</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this branch</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>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.branches.v1_branches_id_PATCH.example"> <title>Example</title> <para> Here we'll update the description of the existing branch <literal >my-project-main</literal>. </para> <programlisting language="json"> PATCH /v1/branches/my-project-main HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Description": "The updated my-project-main 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.branches.v1_branches_id_DELETE"> <title><literal>DELETE /v1/branches/[branch]</literal></title> <para> Removes the branch specification. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.branches.v1_branches_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>branch</literal></entry> <entry>The branch name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.branches.v1_branches_id_DELETE.example"> <title>Example</title> <para> Delete the branch <literal>my-project-main</literal> </para> <programlisting language="json"> DELETE /v1/branches/my-project-main 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/branches.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. |