<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.files" 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>File browsing and upload methods</title> <para> The methods allow for intuitive listing of the depots, directories, and files of your Perforce server. We generally list all elements at a particular directory level, essentially combining output of different commands as needed. </para> <para> The methods here also provide for a upload-style mechanism to create new versions of files in the 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.files.v1_files_GET"> <literal>GET /v1/files</literal> </link> </para> </entry> <entry> <para>Browse and access file, depot, and directory metadata.</para> </entry> </row> <row> <entry> <para> <link linkend="api.files.v1_files_PATCH"> <literal>PATCH /v1/files</literal> </link> </para> </entry> <entry> <para>Update the Content of one or more files.</para> </entry> </row> <row> <entry> <para> <link linkend="api.files.v1_files_DELETE"> <literal>DELETE /v1/files</literal> </link> </para> </entry> <entry> <para>Delete a single file</para> </entry> </row> </tbody> </tgroup> </informaltable> <section xml:id="api.files.v1_files_GET"> <title> <literal>GET /v1/files</literal> </title> <para> Lists the files, directories, and depots at a particular level. </para> <para> By appending to the path, you can descend to the next level of files and directories. Thus, the <literal>GET /v1/files</literal> command lists the depots in the server, <literal>GET /v1/files/my_depot</literal> lists the directories and files at the root level of the <literal>my_depot</literal> depot, and <literal>GET /v1/files/my_depot/my_dir</literal> lists the directories and files of the path<literal>//my_depot/my_dir</literal>, and so on. </para> <para> When you specify a single file in the path, we will return the metadata for the file, along with the <literal>Content</literal> field, which contains the content for the latest version of the file. </para> <para> Please note that the Perforce server will not return a 404 for a directory that does not exist. You will simply get an empty list. A mistyped depot will probably result in an error. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.files.v1_files_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>Path appended to /v1/files</entry> <entry> <para> The directory depot path, minus the preceding '/', e.g., <literal>/depot/dir1</literal> for the depot path <literal>//depot/dir1</literal>. This should not contain wildcards. If you require wildcard usage, use the URL parameter variation. </para> </entry> <entry> Path string </entry> <entry> URL path </entry> <entry> No </entry> </row> <row> <entry>path URL parameter</entry> <entry> <para> The directory depot path, minus the preceding '/', e.g., <literal>depot/dir1</literal> for the depot path <literal>//depot/dir1</literal>. This can utilize Perforce wildcards, in which case your output will only contain the output of files, and not depots or directories. </para> </entry> <entry> Path string </entry> <entry> URL parameter </entry> <entry> No </entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.files.v1_files_GET.response_data"> <title>Response Data</title> <para> There are three different kinds of responses that are possible from the listing command; depots, which are generally only there when there's no path, directories, and files. </para> <bridgehead>Depot Response Data</bridgehead> <para> The depot responses return 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 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> <bridgehead>Directory Response Data</bridgehead> <para> The depot responses return fields available from the <literal>p4 -ztag dirs</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_dirs.html"> <literal>p4 dirs</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>Dir</entry> <entry>The depot path of the directory</entry> <entry>string</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> <bridgehead>File Response Data</bridgehead> <para> The file responses return fields available from the <literal>p4 -ztag files</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_files.html"> <literal>p4 files</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>DepotFile</entry> <entry>The depot path of the file</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry>Revision</entry> <entry>The latest revision number of the file</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry>Change</entry> <entry>The changelist number that created the file revision</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry>Action</entry> <entry>The type of revision action that created the file revision</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry>Type</entry> <entry>The file type</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry>Date</entry> <entry>The timestamp when the revision was created</entry> <entry>number</entry> <entry>Yes</entry> </row> <row> <entry>Content</entry> <entry>Base64 encoded file content, only available when accessing this method for a single file.</entry> <entry>string</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.files.v1_files_GET.examples.depot"> <title>Depot Example</title> <para> Here we'll list the depots available in a new Perforce server. </para> <programlisting> GET /v1/files HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> The typical response will have a list of depot resources: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [{ "Depot": "depot", "Date": 1416846271, "Type": "local", "Map": "depot/...", "Description": "Default depot" }]</programlisting> <para> Note that in even simple cases (just one depot), you will have a list of depots. </para> </simplesect> <simplesect xml:id="api.files.v1_files_GET.examples.directory"> <title>Directory Example</title> <para> Here we'll list files and folders of a particular directory in a new Perforce server. In this case, it's the path <literal>yagg/yaggapp</literal> in the depot <literal>depot</literal>. </para> <programlisting> GET /v1/files/depot/yagg/yaggapp HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Here's a response with one file and one directory: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [ { "DepotFile": "//depot/yagg/yaggapp/build.gradle", "Revision": "1", "Change": "1", "Action": "add", "Type": "text", "Date": 1410899745 }, { "Dir": "//depot/yagg/yaggapp/src" } ]</programlisting> </simplesect> </section> <section xml:id="api.files.v1_files_PATCH"> <title><literal>PATCH /v1/files[/*path]</literal></title> <para> Upload new file content. </para> <para> There are two different kinds of requests here, one for a single file, and another for multiple files. The differences are relatively minor, the JSON bodies are close enough that we treat them similarly. You can, for instance, just use the multiple-file format throughout. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.files.v1_files_PATCH.parameters"> <title>Request Parameters and 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>*path</literal></entry> <entry>The path to the file or directory. For single file mode, this will indicate the file content being updated, and is required. For multiple file uploads, this can indicate a root path that all file <literal>DepotFile</literal> fields are relative to.</entry> <entry>path string</entry> <entry>URL path</entry> <entry>Yes for single files, No for multiple</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>Textual description of the changes made in the upload</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Content</literal></entry> <entry>For single file mode, the Base64 encoded content</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Files</literal></entry> <entry> For multiple file mode, this is the array of files to update. (See below.) </entry> <entry>array</entry> <entry>body</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> <para> For multiple file mode, the each object entry should have these two 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 path to the file. If the directory is specified via the URL path, this can be a relative path from that root directory.</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Content</literal></entry> <entry>Base64 encoded content for the file</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.files.v1_files_PATCH.example"> <title>Examples</title> <para> Upload a single file to <literal>//depot/dev/my_project/README</literal>: </para> <programlisting language="json"> PATCH /v1/files/depot/dev/my_project/README HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj { "Content": "a24bcc..." }</programlisting> <para> The response will only contain the normal HTTP status information. </para> <programlisting> HTTP/1.1 200 OK</programlisting> <para> Now, upload two files to <literal>//depot/dev/my_project</literal>: </para> <programlisting language="json"> PATCH /v1/files/depot/dev/my_project HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj { "Description": "Adding README and Makefile", "Files": [ { "DepotFile": "README", "Content": "12aBd28..." }, { "DepotFile": "Makefile", "Content": "12aBd28..." }, ] }</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.files.v1_files_DELETE"> <title><literal>DELETE /v1/files/*path</literal></title> <para> Delete a single file. </para> <para> This method requires authentication. See <link linkend="userprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.files.v1_files_DELETE.parameters"> <title>Request Parameters</title> <para> The only parameters are the path to the file. </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>*path</literal></entry> <entry>The path to the file, minus the preceding <literal>//</literal></entry> <entry>string</entry> <entry>URL subpath </entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.files.v1_files_DELETE.example"> <title>Example</title> <para> Delete the file <literal>//depot/dev/my_project/Example</literal> </para> <programlisting language="json"> DELETE /v1/files/depot/dev/my_project/Example 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/files.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. |