Files [GET, POST, DELETE] – CDD Support

API calls related to file objects:

Retrieve

Create

Delete

File types and their editing lifecycles

Class	Purpose	Action when edited via ELN
"uploaded file"	The basic file type	Original is preserved and an "editing file" copy is created with a new id.
"editing file"	A file being edited via the ELN	Contents are replaced by the new version. Once editing is finished, the file becomes an "uploaded file" with the same id.
"data file"	A file on the Import Data tab	Original is preserved and an "editing file" copy is created with a new id.
"gzipped data file"	A gzipped file on the Import Data tab	N/A
"zipped data file"	A zipped file on the Import Data tab	N/A
"file in zip"	A file extracted from a zipped data file during the import process	Original is preserved and an "editing file" copy is created with a new id.

Retrieve

Return a single file

GET /api/v1/vaults/<vault_id>/files/<file_id>

Note: The contents are base64 encoded

Example

curl -H "X-CDD-Token: $TOKEN" -X GET "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/files/<file_id>"

Returns:

N.B. "mime_type" returns fields "hash" and "symbol". These are internal fields for the mime type objects in Rails and should be ignored. The fields "string" and "synonyms" can be used as full mime types of the file.

{
  "id": 1069448031,
  "class": "uploaded file",
  "name": "tmp.txt",
  "mime_type":
  {
    "synonyms": [],
    "symbol": "text",
    "string": "text/plain",
    "hash": -1147906696977776415
  },
  "character_set": "US-ASCII",
  "contents": "VGhpcyBpcyBhIGZpbGUK"
}

Following this up with:

echo VGhpcyBpcyBhIGZpbGUK | base64 -D

Returns:

This is a file

Note: "This is a file" is the actual content of this text file

Create

Attach a file to an object (Run, Molecule, Protocol or ELN entry)

POST /api/v1/vaults/<vault_id>/files

Example (adding a file to a Protocol Run)

curl -H "X-CDD-Token: $TOKEN" -X POST --form "file=@C:\files\<file_name>" --form "resource_class=run" --form "resource_id=<run_id>" "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/files"

Returns:

{
   "id": "1069448044"
   "name": "<file_name>"
}

Note: Additional allowed values for resource_class are "molecule", "protocol" and "eln_entry".

Example (adding a file to an ELN Entry)

curl -H "X-CDD-Token: $TOKEN" -X POST --form "file=@C:\files\<file_name>" --form "resource_class=eln_entry" --form "resource_id=<eln_entry_id>" "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/files"

Returns:

{
   "id": "7395612976"
   "name": "<file_name>"
}

Note: To add a file into an ELN entry, the entry must already exist. ELN Entries can be created (by Vault Administrators only) using the POST eln/entries API call.

Attach a file to a Molecule/Batch field or a Protocol Readout Row

There is a 2-step API workflow available now to programmatically attach files to Molecule/Batch fields and to Protocol readouts.

The first step involves using the POST Files API end point to send a file to the CDD Vault server. This step returns an internal file id that must be used in a 2nd API call to attach this file to the desired field/readout.

Step 1
The 1st API call used is POST /api/v1/vaults/<vault_id>/files which returns JSON containing the internal file id.

{
"id": 20167608,
"name": "FlowCyto.png",
"expires_at": "2023-10-13"
}

Helpful Hint: The JSON also includes an “expires_at” date indicating when the file you just sent to the CDD Vault server will no longer exist if it’s not subsequently attached to a field/readout.

Step 2

The next API call should attach the file to the desired field/readout. This step uses the PUT Molecules, PUT Batches or PUT Readout_Rows end points.

PUT /api/v1/vaults/<vault_id>/molecules

PUT /api/v1/vaults/<vault_id>/batches

PUT /api/v1/vaults/<vault_id>/readout_rows

Example (adding a file to a Batch field)

As an example, if the file just POSTed needs to be attached to an existing Batch field, use this API call:

PUT https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/batches/<batch_id>

And pass JSON like this:

{"batch_fields":
{"DataFile": 20167608}
}

Example (adding a file to an existing Readout Row)

As another example, if the file just POSTed needs to be attached to an existing Protocol readout row, use this API call:

PUT https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/readout_rows/<readout_row_id>

And pass JSON like this:

{"readouts":
{"1146750": {"value": "20167608"}}
}

Delete

Delete a file attachment

DELETE /api/v1/vaults/<vault_id>/files/<file_id>

Deletes a single file.

Note: This action is only possible for files with "class": "data file" which are not actively being imported and do not have committed data associated with them.

Example

curl -H "X-CDD-Token: $TOKEN" -X DELETE "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/files/<file_id>"

Returns:

{
      "message": "File with ID <file_id> has been destroyed"
}