files.asc #2

=== Helix Versioning Engine Files

[[get_p4_vX_files]]
==== `GET /p4/v[api]/files/[path]`

Lists file information in the system.
Responses are a combination of the output of three different common `p4` commands: http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_depots.html[`p4 -ztag depots`], http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_dirs.html[`p4 -ztag dirs`], and http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_files.html[`p4 -ztag files`].
We only list file information about the _latest_ version of files.
Files whose latest version is deleted, are not listed in the output.

WARNING: While you can retrieve the contents of files by specifying files instead of directories with the `path` parameter, understand this will very likely fail with large files.
By default, the system is set up with a 60 second timeout, and large files will likely take longer than that to transfer.
For file operations, especially for large files, you should consider using the P4API, and managing a local Helix Versioning Engine client workspace directly to the Helix Versioning Engine.
Helix Web Services is intended for metadata-oriented operations.

===== Request URL Path Parameters

[cols="3*", options="header"]
|===
| Parameter
| Required
| Description

| `api`
| Yes
| The Helix Versioning Engine API level.

| `path`
| No
| A path-like string to a depot or directory that contains other directories or files.
  Do not include wildcards.
|===

===== Request Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Authorization`
| See <<authentication>>

| `Accept`
| `application/json`

| `Content-Type`
| `application/json`

| `X-Perforce-Helix_Web_Services-*`
| See <<per_request_configuration>>
|===

===== Response Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Content-Type`
| `application/json`
|===

===== Response Body JSON

Responses are a combination of the output of three different common `p4` commands: http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_depots.html[`p4 -ztag depots`], http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_dirs.html[`p4 -ztag dirs`], and http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_files.html[`p4 -ztag files`].

See <<error_responses>> for the format of failures.

An example response body might look like:

[source,json]
----
[
  {
    "depotFile": "//depot/dev/Experimental/new_file_RQTWSTFB",
    "rev": "1",
    "change": "190",
    "action": "add",
    "type": "text",
    "time": "1438031186"
  },
  {
    "dir": "//depot/dev/Experimental/subdir"
  }
]
----

If you don't include a path, you'll end up with a list of depots, which looks like this:

[source,json]
----
[
  {
    "name": "depot",
    "time": "1437690306",
    "type": "local",
    "map": "depot/...",
    "desc": "Default depot"
  },
  {
    "name": "stream-test",
    "time": "1437690307",
    "type": "stream",
    "map": "depot/...",
    "desc": "A test depot\n"
  }
]
----

===== Ruby Client

See link:./helix_web_services_client_ruby/HelixWebServicesClient.html#files-instance_method[`HelixWebServicesClient#files`]

Recall that this method will return an `OpenModel`, that can assist in matching the different fields:

[source,ruby]
----
results = client.files
results.concat(client.files('//depot/dir')

names = results.map(&:name_or_dir_or_depot_file)
               .map{ |x| x.split('/').last }
----




[[patch_p4_vX_files]]
==== `PATCH /p4/v[api]/files/[path]`

Provides a means for uploading content to a particular file or directory.
This is a simplification of the <<post_p4_vX_changes>> method, where action is always `upload` on all files.

Note that this works primarily around a classic concept of Perforce, where `path` is really a classic depot path.
For streams, this concept of a path breaks down, since streams are in many ways workspaces, and can import paths from other streams or depot locations.
The streams interface has, as of yet, not been implemented.

===== Request URL Path Parameters

[cols="3*", options="header"]
|===
| Parameter
| Required
| Description

| `api`
| Yes
| The Helix Versioning Engine API level.

| `path`
| No
| A path-like string to a depot or directory that contains other directories or files.
  Do not include wildcards.
|===

===== Request Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Authorization`
| See <<authentication>>

| `Accept`
| `application/json`

| `Content-Type`
| `application/json`

| `X-Perforce-Helix_Web_Services-*`
| See <<per_request_configuration>>
|===

===== Request JSON Body

The Request JSON is an object with the following top-level parameters:

[cols="3*", options="header"]
|===
| Property
| Required
| Description

| `Description`
| No
| A text field describing the new file changes

| `Files`
| No
| For multiple files, this is an array of objects, each containing the same `DepotFile` and `Content` data you would use as if this were a single file upload.

| `DepotFile`
| No
| If this is a single file upload, this is the file path, relative to the `path` parameter in the URL.

| `Content`
| No
| If this is a single file upload, this is the base64-encoded content
|===

For example, here is a request uploading a single file with no URL `path` parameter in the request:

[source,json]
----
{
  "DepotFile": "depot/dir/complete/path",
  "Content": "SSdtIGEgbGl0dGxlIHRlYXBvdAo="
}
----

And here'a request uploading two files, expecting the `path` parameter in the request URL to be set to `depot/dir/complete`:

[source,json]
----
{
  "Files": [
    {
      "DepotFile": "README",
      "Content": "SSdtIGEgbGl0dGxlIHRlYXBvdAo="
    },
    {
      "DepotFile": "test.txt",
      "Content": "SSdtIGEgbGl0dGxlIHRlYXBvdAo="
    }
  ]
}
----

Both of the above requests would upload files to the same directory location.

===== Response Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Content-Type`
| `application/json`
|===

===== Response JSON Body

See <<error_responses>> for the format of failures.

===== Ruby Client

See link:./helix_web_services_client_ruby/HelixWebServicesClient.html#upload_files-instance_method[`HelixWebServicesClient#upload_files`], or link:./helix_web_services_client_ruby/HelixWebServicesClient.html#upload_file-instance_method[`HelixWebServicesClient#upload_file`].




[[delete_p4_vX_files]]
==== `DELETE /p4/v[api]/files/[path]`

Deletes a file if it exists in the system.
This will mark the 'head' revision of the file as deleted.
For more information, see the link:http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_delete.html[`p4 delete`] command reference.

===== Request URL Path Parameters

[cols="3*", options="header"]
|===
| Parameter
| Required
| Description

| `api`
| Yes
| The Helix Versioning Engine API level.

| `path`
| Yes
| A path-like string to a depot or directory that contains other directories or files.
  Do not include wildcards.
|===

===== Request Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Authorization`
| See <<authentication>>

| `Accept`
| `application/json`

| `Content-Type`
| `application/json`

| `X-Perforce-Helix_Web_Services-*`
| See <<per_request_configuration>>
|===

===== Response Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Content-Type`
| `application/json`
|===

===== Response JSON Body

See <<error_responses>> for the format of failures.

===== Ruby Client

See link:./helix_web_services_client_ruby/HelixWebServicesClient.html#delete_file-instance_method[`HelixWebServicesClient#delete_file`]