July 20, 2022
Hello, CDD Vault users! For most of us, summer is well under way - summer or not, we hope you are enjoying whatever season your location brings!
This Vault Snack is for our community of API users. The Application Programming Interface (API) provides secure programmatic access to your CDD Vault data and is very handy for automating routine tasks and integrating with other applications. CDD Vault and the API are a key part to our customers collaborative ecosystem and we thought we'd highlight a few recent enhancements that might change how you're using the API today.
Nearly all of the CDD API endpoints have a number of supported parameters which can be passed when making API calls. Historically, these parameters are passed by adding them directly to the url used in the API call. However, with so many useful parameters available, the combination of these may make the url unwieldy. We'd like to recommend a "best-practice" method for passing parameters so they no longer have to be added to the url.
Instead, create a JSON file containing all of the parameters you wish to submit and then reference your JSON file in your API call. As an example, use the GET Molecules API endpoint to perform an exact structure match and pass this StructureSearch.json file:
{"created_after":"2022-03-15",
"no_structures":"true",
"projects":"7090",
"structure": "CCCCCC1=CC(CC)SC1=O",
"structure_search_type": "exact"}
And now, let's review our list of recent API enhancements.
Summary of All Fields
The GET Fields endpoint will return lists of all internal, molecule, batch and protocol fields. These IDs are necessary when mapping data during a bulk import and can be helpful when syncing data between systems.
Additional Protocol Statistics
An additional protocol statistics section of JSON was added to the GET Protocol API call. Useful for obtaining Z' Factor scores, Positive/Negative Control stats and details on a Reference Curve when your Protocol definition is normalizing data or performing dose-response calculations.
Additional Run Statistics Information and Run ELN Entry Details
The GET Runs API endpoint returns the same information as what is displayed interactively in the Run Summary page, including a new statistics section of the JSON. This call also includes ELN Entry references for Runs that are created from an ELN Entry.
Update Existing Readout Rows (Flag Outliers)
The PUT Readout_Rows API endpoint allows you to update existing readout rows and flag a readout as an outlier via the API. Similarly, the new DELETE Readout_Rows API endpoint allows you to delete an existing readout row.
Create and Populate ELN Entries
New endpoints were added to the API so that new CDD Vault ELN entries can be created & populated, and files can be attached within existing ELN entries. The POST ELN Entries API call will create/populate a new ELN entry while the POST Files API call will attach files to an ELN entry.
Retrieve Dose-Response Images
API scripts may now retrieve images of dose-response curves/plots by using the GET Plots API call.
Information on Existing Mapping Templates
Information on existing mapping templates in CDD Vault are available via the Get Mapping Templates API end-point, which returns summary information for all available templates in the specified Vault.
Automatically Rejecting and Mapping Data Imports
Imports will auto-reject by default when Suspicious Events or Errors occur unless an explicit autoreject=false parameter is included with the POST Slurps API call. This allows other file imports in the queue to continue processing. A new syntax is also available to create field-header mappings (ie, mapping templates) directly from the POST slurps API call. These on-the-fly mappings can be submitted with each import and saved as a mapping template for future imports.
Programmatically Deleting Plates
The Delete Plates API endpoint allows users to remove Plates from CDD Vault.
Lookup Plates Using Names and Locations
Retrieving Plates via the API using Plate Names and Plate Locations (instead of only the internal Plate ID) is possible via the GET Plates API call.
Performing Searches via the API
Searching over chemical structures, Molecule fields, and Batch fields is now possible via the GET Molecules and GET Batches API calls.
Limiting Data Returned Via API Calls
The "only_ids" parameter on the GET Molecules, GET Batches, GET ELN Entries and GET Protocols API calls allows you to return only the relevant object IDs instead of all associated data. This reduces the amount of data and time, and can be useful to determine if objects are deleted.
The "no_structures" parameter on the GET Molecules and GET Batches API calls allows you to omit the structural information from the resulting JSON. This, too, allows for a faster response and avoids passing along sensitive structural information.
The "molecule_fields" and "batch_fields'' parameters for the GET Molecules and GET Batches API let you specify exactly which fields you'd like to return. By default all fields are returned and you can specify a non-existent field, e.g. -1 to not return any fields.
If this Vault Snack leaves you hungry for more, all previous Vault Snacks can be found here and as always, feel free to contact CDD Support - we are available to help you succeed in using CDD Vault.