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.

Important

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:

  • Specific file revision number: fileRevision=#nnn
  • File revision in a pending or submitted changelist: fileRevision=@=nnn
  • File revision in a submitted changelist only: fileRevision=@nnn

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

Important

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.

Note

Requirements:

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
}