<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.changes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" > <title>Changes: Read and create changes</title> <para> The method here allows for summarizing history with some common filters. </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.changes.v1_changes_GET"> <literal>GET /v1/changes</literal> </link> </para> </entry> <entry> <para>List changelist summaries </para> </entry> </row> <row> <entry> <para> <link linkend="api.changes.v1_changes_id_GET"> <literal>GET /v1/changes/[change]</literal> </link> </para> </entry> <entry>Describe a single changelist</entry> </row> <row> <entry> <para> <link linkend="api.changes.v1_change_POST"> <literal>POST /v1/changes</literal> </link> </para> </entry> <entry>Create a new change with multiple file operations.</entry> </row> </tbody> </tgroup> </informaltable> <section xml:id="api.changes.v1_changes_GET"> <title><literal>GET /v1/changes</literal></title> <para> List changelist summaries, with some common filtering options. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.changes.v1_changes_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>max</entry> <entry>Limit the number of results</entry> <entry>number</entry> <entry>URL parameter</entry> <entry>No</entry> </row> <row> <entry>status</entry> <entry><literal>pending</literal>, <literal>submitted</literal>, or <literal>shelved</literal></entry> <entry>string</entry> <entry>URL parameter</entry> <entry>No</entry> </row> <row> <entry>user</entry> <entry>The Perforce login of the user who owns the change</entry> <entry>string</entry> <entry>URL parameter</entry> <entry>No</entry> </row> <row> <entry>files</entry> <entry>A file pattern that should match files affected by the changelist</entry> <entry>string</entry> <entry>URL parameter</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.changes.v1_changes_GET.response_data"> <title>Response Data</title> <para> Most of the information here is based off of the <literal>p4 -ztag changes</literal> output. For more information please refer to the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_changes.html"> p4 changes 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>Change</entry> <entry>The changelist number</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry>Description</entry> <entry>The changelist summary description</entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry>Status</entry> <entry><literal>pending</literal>, <literal>submitted</literal>, or <literal>shelved</literal></entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry>Type</entry> <entry><literal>restricted</literal>, or <literal>public</literal></entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry>Path</entry> <entry>Region of the depot affected by the changelist</entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry>Client</entry> <entry>The Perforce client workspace name that created the change</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry>User</entry> <entry>The Perforce login who created the changelist</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry>Date</entry> <entry>The timestamp of when the change was created</entry> <entry>number</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.changes.v1_changes_GET.example"> <title>Example</title> <para> List the changes made underneath <literal>//depot/swarm-development-kit/...</literal> by user <literal>jdoe</literal>. </para> <programlisting> GET /v1/changes?user=jdoe&files=//depot/swarm-development-kit/... HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Here's a response with one changelist: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [ { "Change": "3", "Date": 1412976404, "User": "jdoe", "Client": "jdoe_client", "Status": "submitted", "Type": "public", "Path": "//depot/swarm-development-kit/...", "Description": "first pass\n" } ]</programlisting> </simplesect> </section> <section xml:id="api.changes.v1_changes_id_GET"> <title><literal>GET /v1/changes/[change]</literal></title> <para> Read details of a single changelist in the system. </para> <para> Unlike the <literal>p4 describe</literal> command, this method does not list the diffs of files in a particular changelist. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.changes.v1_changes_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>change</literal></entry> <entry> The Perforce changelist number </entry> <entry> string </entry> <entry> URL path </entry> <entry> No </entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.changes.v1_changes_id_GET.response_data"> <title>Response Data</title> <para> The responses return fields available from <literal>p4 -ztag describe</literal> command. You can review the the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_describe.html"> <literal>p4 describe</literal> </ulink> command reference, however, please be aware that the tagged output differs from the console command. </para> <para> The main set of fields for changelists are: </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>Change</literal> </entry> <entry>The changelist ID</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Description</literal> </entry> <entry>A textual description of the change</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Date</literal> </entry> <entry>The timestamp the change was created</entry> <entry>number</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Client</literal> </entry> <entry>The client ID used to submit the change</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry> <literal>User</literal> </entry> <entry>The Perforce login of who created the change</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Type</literal> </entry> <entry>The type of changelist, probably<literal>public</literal>, or, <literal>restricted</literal> </entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Status</literal> </entry> <entry>The changelist status, probably<literal>pending</literal>, <literal>shelved</literal>,<literal>submitted</literal>, or <literal>new</literal>. </entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Path</literal> </entry> <entry>The part of the depot affected by this changelist</entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry> <literal>Files</literal> </entry> <entry>Array of file changes (see below)</entry> <entry>array</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> <para> Description of each entry in the <literal>Files</literal> array for changes. </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>DepotFile</literal> </entry> <entry>The depot path to the file</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Action</literal> </entry> <entry>The kind of action taken on the file. For example, <literal>branch</literal>,<literal>add</literal>, <literal>edit</literal>,<literal>delete</literal>, <literal>move/delete</literal>,<literal>move/add</literal>. </entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Revision</literal> </entry> <entry>The file revision created by this entry</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry> <literal>Digest</literal> </entry> <entry>A digest string for submitted changes.</entry> <entry>string</entry> <entry>No</entry> </row> <row> <entry> <literal>FileSize</literal> </entry> <entry>The file size, in bytes, for submitted changes</entry> <entry>String</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.changes.v1_changes_id_GET.example"> <title>Example</title> <para> Fetch the description of change 5. </para> <programlisting> GET /v1/changes/5 HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Typical JSON response: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [{ "Path": "//depot/dev/Experimental/*", "Change": "5", "Date": 1418922083, "Client": "BADFJRZI", "User": "jdoe", "Status": "submitted", "Type": "public", "Description": "Uploaded files\n", "Files": [ { "DepotFile": "//depot/dev/Experimental/new_file", "Action": "add", "Revision": "1", "Digest": "3D65EFC8CA18C21F7BEB78E47AE94206", "FileSize": "16" }, { "DepotFile": "//depot/dev/Experimental/README", "Action": "edit", "Revision": "3", "Digest": "79D26F4E7F23D662E51F45896891D7C1", "FileSize": "22" } ] }]</programlisting> </simplesect> </section> <section xml:id="api.changes.v1_change_POST"> <title><literal>POST /v1/changes</literal></title> <para> Create a new changelist that can affect multiple files using different kinds of actions. If you require the ability to <literal>integrate</literal> or <literal>move</literal>, for example, you will use this method. </para> <para> This method requires authentication. See <link linkend="userprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.changes.v1_change_POST.request"> <title>Request Body</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>Description</literal></entry> <entry>Textual description of the change</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Files</literal></entry> <entry>Array of file change actions to take (See below)</entry> <entry>array</entry> <entry>body</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> <para> Each object in the <literal>Files</literal> array consists of the following fields: </para> <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>DepotFile</literal></entry> <entry>The depot path specifier for the action</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>FromDepotFile</literal></entry> <entry>When the <literal>Action</literal> is a <literal>branch</literal> or <literal>move</literal>, this indicates the source of the operation.</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Action</literal></entry> <entry>One of <literal>upload</literal>, <literal>branch</literal>, or <literal>move</literal>.</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Content</literal></entry> <entry>If the <literal>Action</literal> is <literal>upload</literal>, this is the base-64 encoded file content.</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.changes.v1_changes_POST.example"> <title>Example</title> <para> Create a new change with one file branched and the other moved. </para> <programlisting language="json"> POST /v1/users HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { 'Description' => 'An integ and a move', 'Files' => [ { 'DepotFile' => '//depot/main/README', 'FromDepotFile' => '//depot/dev/README', 'Action' => 'branch' }, { 'DepotFile' => '//depot/main/to', 'FromDepotFile' => '//depot/main/from', 'Action' => 'move' } ] }</programlisting> <para> The response should indicate 200 on success. </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/changes.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. |