<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.labels" 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> Labels - List and manage label specifications </title> <para> These methods allow you to list, edit, and maintain label 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.labels.v1_labels_GET"> <literal>GET /v1/labels</literal> </link> </para> </entry> <entry> <para>List available labels</para> </entry> </row> <row> <entry> <para> <link linkend="api.labels.v1_labels_POST"> <literal>POST /v1/labels</literal> </link> </para> </entry> <entry> <para>Create a new label specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.labels.v1_labels_id_GET"> <literal>GET /v1/labels/[label]</literal> </link> </para> </entry> <entry> <para>Describe a single label specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.labels.v1_labels_id_PATCH"> <literal>PATCH /v1/labels/[label]</literal> </link> </para> </entry> <entry> <para>Update a label specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.labels.v1_labels_id_DELETE"> <literal>DELETE /v1/labels/[label]</literal> </link> </para> </entry> <entry> <para>Delete a label specification</para> </entry> </row> </tbody> </tgroup> </informaltable> <section xml:id="api.labels.v1_labels_GET"> <title><literal>GET /v1/labels</literal></title> <para> Lists available labels in the system. </para> <para> The resources of this list are summaries of labels in the system. For more details of each label, append the <literal>label</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.labels.v1_labels_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag labels</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_labels.html"> <literal>p4 labels</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>Label</literal></entry> <entry>The label name and primary ID</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Owner</literal></entry> <entry>The Perforce login of the owning user</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>The Label's options</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>Text describing the Label</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Update</literal></entry> <entry>The timestamp the label specification was last modified.</entry> <entry>number</entry> <entry>Yes</entry> </row> <row> <entry><literal>Access</literal></entry> <entry> The timestamp the label was last accessed, either by running <literal>p4 labelsync</literal> on the label, or by otherwise referring to a file with the label revision specifier <literal>@label</literal>. (Note: Reloading a label with <literal>p4 reload</literal> does not affect the access time.) </entry> <entry>number</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.labels.v1_labels_GET.example"> <title>Example</title> <para>Our standard authenticated request format for listing labels:</para> <programlisting> GET /v1/labels HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Here's an example of a list with one label in the response: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [{ "Update": 1416869533, "Access": 1416869533, "Owner": "jdoe", "Options": "unlocked noautoreload", "Description": "Created by jdoe.\n", "Label": "example_label" }]</programlisting> </simplesect> </section> <section xml:id="api.labels.v1_labels_POST"> <title><literal>POST /v1/labels</literal></title> <para> Creates a new label specification. </para> <para> Upon success, this will return a 303 redirect to the new label specification resource that has been created. </para> <para> If the label already exists, this method will replace the existing label completely. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.labels.v1_labels_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>Label</literal></entry> <entry>The name of the label</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this label</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>The label's options</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>View</literal></entry> <entry>The array of depot paths that restrict the taggable files for the label</entry> <entry>array</entry> <entry>body</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.labels.v1_labels_id_POST.example"> <title>Example</title> <para> We'll create a simple label <literal>my_product_0.1</literal>. </para> <programlisting language="json"> POST /v1/labels HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Label": "my_product_0.1", "View": ["//depot/main/my_product/..."] }</programlisting> <para> The return value should be a redirect to the details page of the new label. </para> <programlisting> HTTP/1.1 303 Found Location: http://example.com/p4/v1/labels/my_product_0.1</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.labels.v1_labels_id_GET"> <title><literal>GET /v1/labels/[label]</literal></title> <para> Return label details. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.labels.v1_labels_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>label</entry> <entry>The label name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.labels.v1_labels_id_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag label</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_label.html"> <literal>p4 label</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>Label</literal></entry> <entry>The name of the label</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this label</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>The label's options</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>View</literal></entry> <entry>The array of depot paths that restrict the taggable files for the label</entry> <entry>array</entry> <entry>Yes</entry> </row> <row> <entry><literal>Update</literal></entry> <entry>The timestamp the label specification was last modified.</entry> <entry>number</entry> <entry>Yes</entry> </row> <row> <entry><literal>Access</literal></entry> <entry> The timestamp the label was last accessed, either by running <literal>p4 labelsync</literal> on the label, or by otherwise referring to a file with the label revision specifier <literal>@label</literal>. (Note: Reloading a label with <literal>p4 reload</literal> does not affect the access time.) </entry> <entry>number</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.labels.v1_labels_id_GET.example"> <title>Example</title> <para> Here is an example request for the label <literal>yagg_0.1</literal>. This is a fairly simple label, containing only one view mapping. </para> <programlisting> GET /v1/labels/yagg_0.1 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 { "Label": "example_label", "Update": 1416869533, "Access": 1416869533, "Owner": "jdoe", "Description": "Created by jdoe.\n", "Options": "unlocked noautoreload", "View": ["//depot/main/..."] }</programlisting> </simplesect> </section> <section xml:id="api.labels.v1_labels_id_PATCH"> <title><literal>PATCH /v1/labels/[label]</literal></title> <para> Update label 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.labels.v1_labels_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>label</literal></entry> <entry>The name of the label</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A textual description of this label</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>The label's options</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>View</literal></entry> <entry>The array of depot paths that restrict the taggable files for the label</entry> <entry>array</entry> <entry>body</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.labels.v1_labels_id_PATCH.example"> <title>Example</title> <para> Here we'll update the description of the existing label <literal >my_product_0.1</literal>. </para> <programlisting language="json"> PATCH /v1/labels/my_product_0.1 HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Description": "The updated my_product_0.1 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.labels.v1_labels_id_DELETE"> <title><literal>DELETE /v1/labels/[label]</literal></title> <para> Removes the label specification. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.labels.v1_labels_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>label</literal></entry> <entry>The label name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.labels.v1_labels_id_DELETE.example"> <title>Example</title> <para> Delete the label <literal>new_label</literal> </para> <programlisting language="json"> DELETE /v1/labels/my_product_0.1 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/labels.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. |