Files: Swarm files
Get file data
Summary
Get file data for the specified file
GET /api/v11/files/{id}
Description
Get file data for the specified file.
You must be authenticated to view the file information.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
id |
File ID, this is the full filepath including the filename encoded to URL safe Base64. Various tools are available online to encode the id to URL safe Base64, for example: https://www.base64encode.org |
string |
path |
Yes |
fileRevision |
Specify the revision of the file using one of the following options:
Where nnn is the revision or changelist number you want. |
string |
query |
No |
Example usage
Get file data for a specific revision of a file
Get file data for //depot/main/myfile.txt revision 3. The full filepath and filename must be encoded in URL safe Base64.
curl -u "username:ticket" "https://myswarm-url/api/v11/files/Ly9kZXBvdC9tYWluL215ZmlsZS50eHQ?fileRevision=#3"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data" : {
"filename":"//depot/main/myfile.txt"
"contentLink": "http://myswarm-url/view/depot/main/myfile.txt",
"fileRevision": "#3",
"contentType": "text/plain",
"changeId": "12871"
}
}
If a request fails
<error code>:
- 400 Invalid file revision specified. Must be one of the following: @ or @= followed by the changelist number, or # followed by the file revision number.
- 403 Insufficient permissions to access the file
- 404 File does not exist
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
File edit
File edit is a Technology Preview feature.
Features offered in Technology Preview mode are unsupported and may not be functionally complete. If you use any features in Technology Preview mode, Perforce would appreciate your feedback and any functionality suggestions before the feature becomes supported. Please email us at techpreview@perforce.com.
Summary
Edit the file content and submit or shelve the file
PUT /api/v11/files/{id}
Description
Edit the file content and submit or shelve the file.
Requirements:
- You must have permissions to edit the file.
- If the file version changes while you are editing it or if you are not editing the Head
The most recent revision of a file within the depot. Because file revisions are numbered sequentially, this revision is the highest-numbered revision of that file. revision of the file, committing your file changes will overwrite the current head revision of the file.
- File edit is enabled by default but can be disabled by your Swarm administrator, see allow_edits.
If you are unsure, shelving your change is a safer option because it will not overwrite the head revision of the file and you can do a manual resolve when you commit the shelf.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
id |
File ID, this is the full filepath including the filename encoded to URL safe Base64. Various tools are available online to encode the id to URL safe Base64, for example: https://www.base64encode.org |
string |
path |
Yes |
content | Specify the entire file content to be shelved or submitted. Lines in the content must be separated with backslash and n characters \n. | string | body | Yes |
description |
Specify a changelist description. Optional: you can create a review for your change or add it to an existing review by including a review keyword in the Change description. For instruction on creating a review and adding a changelist to a review using review keywords, see Create a review and Add a changelist to a review. |
string | body | No |
action | Specify the file action as either shelve or submit. | string | body | Yes |
Example usage
Shelve file with edited content
Shelve //depot/main/myfile.txt file with edited content. The full filepath and filename must be encoded in URL safe Base64.
curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/files/Ly9kZXBvdC9tYWluL215ZmlsZS50eHQ"
The "mybodyfilename.txt" file contains the file content, description and the shelve action:
{
"content": "My original line\nMy nice new line\nAnother original line"
"description": "Added a new line."
"action": "shelve"
}
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data" : {
"filename":"//depot/main/myfile.txt"
"contentLink": "http://myswarm-url/view/depot/main/myfile.txt",
"fileRevision": "@=12896",
"contentType": "text/plain",
"changeId": "12896"
}
}
If a request fails
<error code>:
- 400 Invalid file revision specified. Must be one of the following: @ or @= followed by the changelist number, or # followed by the file revision number.
- 403 Insufficient permissions to submit or shelve the file
- 404 File does not exist
- 500 Submit command failed because a newer revision of the file exists, you must resolve and submit your changes or revert your changes.
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}