changes.asc #2

=== Helix Versioning Engine Changes

[[get_p4_vX_changes]]
==== `GET /p4/v[api]/changes`

List changelist summaries, with some common filtering options.

===== Request URL Path Parameters

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

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

===== Request URI Query Parameters

The following parameters are all optional.

[cols="2*", options="header"]
|===
| Key
| Description

| `max`
| Limits the number of results returned
  See the link:http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_changes.html[changes -m] option.

| `status`
| Only return results with the indicated status.
  See the link:http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_changes.html[changes -s] option.

| `user`
| Only return changes owned by this particular user.
  See the link:http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_changes.html[changes -u] option.

| `files`
| Limit changes to the depot path expressions.
  See the link:http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_changes.html[changes] command description.
|===

===== 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

The values of this method are based on the result of the http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_changes.html[`p4 -ztag changes`] command.

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

An example response body might look like:

[source,json]
----
[
  {
    "change": "20",
    "time": "1437589210",
    "user": "jdoe",
    "client": "AUERUGBO",
    "status": "submitted",
    "changeType": "public",
    "path": "//depot/dev/Experimental/*",
    "desc": "Upload two experimental files\n"
  },
  {
    "change": "19",
    "time": "1437589209",
    "user": "jdoe",
    "client": "PRQSCBCT",
    "status": "submitted",
    "changeType": "public",
    "path": "//depot/test-UDQXTCFI/Experimental/*",
    "desc": "Edited files\n"
  }
]
----

===== Ruby Client

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




[[post_p4_vX_changes]]
===== `POST /p4/v[api]/changes`

Create a new changelist that can affect multiple files using different kinds of actions.
If you require the ability to integrate or move, for example, you can use this method.

The `upload` capability works around the classic depot concept of Perforce.
This means that there is no (as of yet) `upload` functionality into streams.

===== Request URL Path Parameters

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

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

===== 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 should be a JSON object with the following properties:

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

| `Description`
| Textual description of the change
| string
| body
| No

| `Files`
| Array of file change actions to take (See below)
| array
| body
| No
|===

Each object in the `Files` array consists of the following properties:

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

| `DepotFile`
| The depot path specifier for the action
| Yes

| `FromDepotFile`
| When the Action is a branch or move, this indicates the source of the operation.
| No

| `Action`
| One of `upload`, `branch`, or `move`.
| Yes

| `Content`
| If the Action is upload, this is the base-64 encoded file content.
| No

| `RequireVersion`
| If the current version is not set at this version string, consider it an error.
| No
|===

An example JSON request body would look like:

[source,json]
----
{
  "Description": "My Test Change",
  "Files": [
    {
      "Action": "upload",
      "DepotFile": "//depot/example.txt",
      "Content": "SSBhbSBhIGxpdHRsZSB0ZWFwb3Q="
    }
  ]
}
----

===== Response Headers

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

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

===== Response JSON

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

===== Ruby Client

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




[[get_p4_vX_changes_change]]
==== `GET /p4/v[api]/changes/[change]`

Read details of a single changelist in the system.

===== Request URL Path Parameters

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

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

| change
| The changelist number.
|===

===== 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

The values of this method are based on the result of the http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_describe.html[`p4 -ztag describe`] command.

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

An example response might look like this:

[source,json]
----
[
  {
    "change": "1",
    "user": "super",
    "client": "JGOJOUDY",
    "time": "1437581534",
    "desc": "A few basic adds\n",
    "status": "submitted",
    "changeType": "public",
    "path": "//depot/...",
    "depotFile": [
      "//depot/dev/Experimental/README",
      "//depot/main/My Project/README"
    ],
    "action": [
      "add",
      "add"
    ],
    "type": [
      "text",
      "text"
    ],
    "rev": [
      "1",
      "1"
    ],
    "fileSize": [
      "40",
      "34"
    ],
    "digest": [
      "5606AFCE00250FC14B2D932BAF5CE45B",
      "0FA2BDFCEACC2A445EFDF86BEB6D3F9F"
    ]
  }
]
----

===== Ruby Client

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




[[post_p4_vX_changes_change]]
==== `POST /p4/v[api]/changes/[change]`

Submit shelved changes to the depot.
Uses the link:http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_describe.html[`p4 submit -e`] command to perform the submit.

This method will fail:

1. If the changelist in question is not a pending changelist with a shelf.
2. If any resolves are required.
3. If any files are open on the pending changelist. You must revert all local changes before calling this method.

If the changelist is based on a stream client, this will generate a temporary stream client as appropriate.

===== Request URL Path Parameters

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

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

| change
| The changelist number.
|===

===== 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.