To upload review materials use the the ReviewService.addFiles command. This command is rather complex and allows different variants of adding materials to a review. The files may reside on your local computer or be stored in a source code management system. Moreover, the command can add files to an existing review or to create a new review.

You will describe the following use-cases:

Depending on the particular use-case, the syntax of the addFiles command and the number of its arguments will vary. For example, to add materials to an existing review you need to specify the "reviewID" argument. If this argument is omitted, the addFiles command will create a new review with the attached files.

On success the addFiles command returns an ID of the review where the files were added.

Add files to a review

To add files that are stored on a local computer you need to archive them beforehand. The archived files must follow special conventions described below.

Once the archive is created you can send it to a Collaborator server and attach files to a review. There are two ways to do this:

Preparing files for upload

Prior to uploading files to the Collaborator server you need to prepare them as follows:

Uploading files via /contentupload servlet

Every Collaborator server has a servlet for uploading data to reviews. It resides at the following URL: yourServer.com/contentupload 

The servlet accepts multipart HTTP requests that contain Zip archives with files. The file upload request must conform to RFC 1867: Form-based File Upload in HTML.

The servlet requires authentication parameters in the request before processing file uploads. Authentication can be provided with the following methods:

Authorization: Basic bXl1c2VyOm15cGFzcw==

Cookie: CodeCollaboratorLogin=jsmith; CodeCollaboratorTicketId=0123456789abcdef0123456789;

If the upload is successful, the servlet will respond with a 200 (OK) status.

Below is an example of multipart HTTP request to the /contentupload servlet:

POST http://yourServer.com/contentupload HTTP/1.1

Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468

User-Agent: JSON API

Host: yourServer.com/

Cookie: CodeCollaboratorLogin=jsmith; CodeCollaboratorTicketId=0123456789abcdef0123456789;

Content-Length: 1394

---------------------------acebdf13572468

Content-Disposition: form-data; name="file"; filename="localFiles.zip"

Content-Type: application/x-zip-compressed

<Binary data of the localFiles.zip file>

---------------------------acebdf13572468--

Once the archive is uploaded successfully, the server unpacks it. Later on the you need to send a command to add an already uploaded files to reviews. To add files that were uploaded beforehand, use the following syntax of the addFiles command:

 {"command" : "ReviewService.addFiles",

  "args" : {

  "reviewId": "<Id>", OPTIONAL

  "changelists" : [{ REQUIRED

         "commitInfo" : {<commitInfo>}, OPTIONAL

         "versions" : [ { REQUIRED

                 "md5" : "<md5Checksum>", REQUIRED

                 "localPath" : "<LocalPathToFile>", OPTIONAL

                 "scmPath" : "<PathToFileInSCM>", OPTIONAL

                 "action" : "<ActionType>", OPTIONAL

                 "source" : "<SourceType>", OPTIONAL

                 "baseVersion" : OPTIONAL

                 }, {<version2>},..., {<versionN>}]

         }, {<changelist2>},..., {<changelistN>}]

  }

When adding already uploaded files, we should specify their MD5 checksums (md5) and either their local paths (localPath) or their paths in SCM (scmPath). All other arguments are optional. Notice that archive name is not specified, as the archive has already been unpacked.

The example below, attaches an uploaded file to the specified review:

[{"command" : "SessionService.authenticate",

         "args" : {"login" : "jsmith","ticket" : "0123456789abcdef0123456789abcdef"}},

 {"command" : "ReviewService.addFiles",

"args" : {

"reviewId" : "10463",

"changelists" : [{

          "versions" : [ { "md5" : "198575c00a884ae27968e2fcf7d0a26d",

          "localPath" : "c:\\work\\collab\\files\\listobject.h",

          "source" : "LOCAL" } ]

          }]

}

}]

Uploading files with a multipart request

In this approach both the JSON commands and one or more archives to be attached are sent in the same multipart request.

The JSON request must be sent in a string part named "json" or as part of the query string as "json" parameter. The attached files must be sent in parts whose names coincides with the archive names. See RFC 1341:  The Multipart Content-Type for detailed description of multipart requests.

To add files that are sent within the same HTTP request, use the following syntax of the addFiles command:

 {"command" : "ReviewService.addFiles",

  "args" : {

  "reviewId": "<Id>", OPTIONAL

  "zipName" : "<zipNameForCommand>", OPTIONAL

  "changelists" : [{ REQUIRED

         "commitInfo" : {<commitInfo>}, OPTIONAL

         "versions" : [ { REQUIRED

                 "md5" : "<md5Checksum>", REQUIRED

                 "zipName" : "<zipNameForChangelist>", OPTIONAL

                 "localPath" : "<LocalPathToFile>", OPTIONAL

                 "scmPath" : "<PathToFileInSCM>", OPTIONAL

                 "action" : "<ActionType>", OPTIONAL

                 "source" : "<SourceType>", OPTIONAL

                 "baseVersion" : OPTIONAL

                 }, {<version2>},..., {<versionN>}]

         }, {<changelist2>},..., {<changelistN>}]

  }

When adding files with a multipart request, we should specify the names of archive (zipName), MD5 checksums of individual files (md5) and either their local paths (localPath) or their paths in SCM (scmPath). The archive name (zipName) can be given at the command level or per changelist. The zipName arguments are interchangeable, however at least one of them must be specified. All other arguments are optional.

As mentioned above, the attached files must be sent in parts whose names matches the values of zipName arguments of the AddFiles command:

--boundary separator

Content-Disposition: form-data; name="<zipName>"; filename="<zipName>"

Content-Type: application/x-zip-compressed

<Binary data of the archive file>

The overall example of a multipart request may look like this:

POST http://yourServer.com/services/json/v1 HTTP/1.1

Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468

User-Agent: JSON API

Host: yourServer.com

Content-Length: 2041

---------------------------acebdf13572468

Content-Disposition: form-data; name="json"

Content-Type: application/json;charset=utf-8

[{"command" : "SessionService.authenticate",

         "args" : {"login" : "jsmith","ticket" : "0123456789abcdef0123456789abcdef"}},

 {"command" : "ReviewService.addFiles",

"args" : {

"reviewId" : "10463",

"changelists" : [{

"zipName" : "localFiles.zip",

"versions" : [ { "md5" : "198575c00a884ae27968e2fcf7d0a26d",

"localPath" : "c:\\work\\collab\\files\\listobject.h",

"source" : "LOCAL" } ]

}]

}

}]

---------------------------acebdf13572468

Content-Disposition: form-data; name="localFiles.zip"; filename="localFiles.zip"

Content-Type: application/x-zip-compressed

<Binary data of the localFiles.zip file>

---------------------------acebdf13572468--

 Add files from source-control system

To add files from source-control system, use the following syntax of the addFiles command:

 {"command" : "ReviewService.addFiles",

  "args" : {

  "reviewId": "<Id>", OPTIONAL

  "changelists" : [{ REQUIRED

         "commitInfo" : {<commitInfo>}, OPTIONAL

         "changelistLog" : ["<changelistID1>", ..., "<changelistIDN>"], OPTIONAL

         "scmConnectionParameters" : ["<ConnectionParam1>", ..., "<ConnectionParamN>"], OPTIONAL

         "scmToken" : "<scmToken>", OPTIONAL

         "versions" : [ { REQUIRED

                 "md5" : "<md5Checksum>", REQUIRED

                 "scmVersionName" : "<FileVersionNameInSCM>", OPTIONAL

                 "scmPath" : "<PathToFileInSCM>", OPTIONAL

                 "action" : "<ActionType>", OPTIONAL

                 "source" : "<SourceType>", OPTIONAL

                 "baseVersion" : OPTIONAL

                 }, {<version2>},..., {<versionN>}]

         }, {<changelist2>},..., {<changelistN>}]

  }

When adding files from source-control system, we should specify their MD5 checksums (md5) and their paths in SCM (scmPath), and connection parameters to SCM (scmConnectionParameters). All other arguments are optional.

The example below attaches files from Git commit with ID 85994af65fb900f6e55606cb5ca498cc54463dbc to review 12:

[  

   {

       "command": "SessionService.authenticate",

       "args": {

           "login": "jsmith",

           "ticket": "0123456789abcdef0123456789abcdef"

       }

   },

   {

       "command": "ReviewService.addFiles",

       "args": {

           "changelists": [

               {

                   "versions": [

                       {

                           "baseVersion": {

                               "source": "CHECKEDIN",

                               "scmVersionName": "40bf3c9346272c4e9eb77e8e379732c922c4f93a",

                               "md5": "f5212826f77081a8f7cfb9c0fed8967b",

                               "scmPath": "foobar/src/main/resources/js/view.js",

                               "action": "MODIFIED",

                               "commitInfo": {

                                   "comment": "Merge pull request #5",

                                   "date": "2020-04-09T18: 57: 51+03: 00",

                                   "author": "GitHub",

                                   "local": false,

                                   "hostGuid": "266a5c8637da6b0c568803161fcb54a3",

                                   "scmId": "28a221d213b28ad1e38e4805b45b13f995bc5d94"

                               }

                           },

                           "source": "CHECKEDIN",

                           "scmVersionName": "18d9ace010a575468b33b231040d4776196606d8",

                           "md5": "cb75d9547200ccc50c4d4142c356d9b3",

                           "scmPath": "foobar/src/main/resources/js/view.js",

                           "action": "MODIFIED"

                       }

                   ],

                   "changelistLog": [

                       "85994af65fb900f6e55606cb5ca498cc54463dbc",

                       "28a221d213b28ad1e38e4805b45b13f995bc5d94"

                   ],

                   "scmConnectionParameters": [

                       "https://github.com/acme/foobar.git"

                   ],

                   "scmToken": "GIT",

                   "commitInfo": {

                       "comment": "Merge pull request #6",

                       "date": "2020-05-05T12:22:34+03:00",

                       "author": "GitHub",

                       "local": false,

                       "hostGuid": "266a5c8637da6b0c568803161fcb54a3",

                       "scmId": "85994af65fb900f6e55606cb5ca498cc54463dbc"

                   }

               }

           ],

           "reviewId": 12

       }

   }

]