In our continuous effort to improve Castor CDMS and align our terminology with industry standards, we have made significant changes to our API terminology in the 2022.4.0.0 release. This article outlines the changes made and provides guidance on how to update your integration, ensuring it continues to work seamlessly with Castor CDMS.
Changes to the API
As of the 2022.4.0.0 release, we have updated several key terms within our API to more accurately reflect their functionality and to ensure consistency with industry standards. The following changes were implemented:
- "Phase" has been changed to “Visit”
- "Step" has been changed to “Form”
- "Record" has been changed to “Participant”
- "Report" has been changed to “Repeating Data”
- “Institute” has been changed to “Site”
- In the API, “surveypackage” has been changed to “survey-package”
Impact on integrations
Endpoints incorporating the previous terminology have been marked as deprecated and will be removed in the 2024.3.0.0 release, scheduled for this summer. To avoid any disruptions to your data management workflows, it is essential to update your integrations to use the new endpoints. We kindly ask you to update your integrations before August 2024.
How to update your integration
For users of the R Package (castoRedc)
If you are using the castoRedc R package to integrate with the Castor CDMS API, upgrading your integration is straightforward. We have updated the R package to version 2.0.0, which supports the new API endpoints and terminology.
Follow these steps to update your package:
- Open your R environment.
- Run the following command to install version 2.0.0 of the castoRedc package:
- remotes::install_github("castoredc/castoRedc")
This command will update your R package to the latest version, ensuring compatibility with the updated Castor CDMS API.
For users with custom integrations
If you have developed a custom integration, you will need to update your API calls to reflect the new terminology and endpoints. We recommend reviewing your current integration code and making the necessary adjustments to use the updated endpoints.
Detailed documentation on the new endpoints and additional guidance on the migration process can be found in our API documentation. A table of old and new endpoint URLs is listed below as well. Our support team is available to assist with any questions or challenges you may encounter during the update process.
|
Category |
Old endpoint |
New endpoint |
|
Survey |
/study/{study_id}/surveypackage |
/study/{study_id}/survey-package |
|
/study/{study_id}/surveypackage/{survey_package_id} |
/study/{study_id}/survey-package/{survey_package_id} |
|
|
/study/{study_id}/surveypackageinstance |
/study/{study_id}/survey-package-instance |
|
|
/study/{study_id}/surveypackageinstance/{survey_package_instance_id} |
/study/{study_id}/survey-package-instance/{survey_package_instance_id} |
|
|
/study/{study_id}/record/{record_id}/surveypackageinstance/{survey_package_instance_id} |
/study/{study_id}/participant/{participant_id}/survey-package-instance/{survey_package_instance_id} |
|
|
Data Point Collection |
/study/{study_id}/record/{record_id}/data-point-collection/study |
/study/{study_id}/participant/{participant_id}/data-points/study |
|
/study/{study_id}/record/{record_id}/data-point-collection/report-instance |
/study/{study_id}/participant/{participant_id}/data-points/repeating-data-instance |
|
|
/study/{study_id}/record/{record_id}/data-point-collection/report-instance/{report_instance_id} |
/study/{study_id}/participant/{participant_id}/data-points/repeating-data-instance/{repeating_data_instance_id} |
|
|
/study/{study_id}/record/{record_id}/data-point-collection/survey-instance |
/study/{study_id}/participant/{participant_id}/data-points/survey-instance |
|
|
/study/{study_id}/record/{record_id}/data-point-collection/survey-instance/{survey_instance_id} |
/study/{study_id}/participant/{participant_id}/data-points/survey-instance/{survey_instance_id} |
|
|
/study/{study_id}/record/{record_id}/data-point-collection/survey-package-instance |
/study/{study_id}/participant/{participant_id}/data-points/survey-package-instance |
|
|
/study/{study_id}/record/{record_id}/data-point-collection/survey-package-instance/{survey_package_instance_id} |
/study/{study_id}/participant/{participant_id}/data-points/survey-package-instance/{survey_package_instance_id} |
|
|
Site |
/study/{study_id}/institute |
/study/{study_id}/site |
|
/study/{study_id}/institute/{institute_id} |
/study/{study_id}/site/{site_id} |
|
|
Study Data Entry |
/study/{study_id}/record/{record_id}/data-point/study |
/study/{study_id}/participant/{participant_id}/data-point/study |
|
/study/{study_id}/record/{record_id}/study-data-point/{field_id} |
/study/{study_id}/participant/{participant_id}/study-data-point/{field_id} |
|
|
Randomization |
/study/{study_id}/record/{record_id}/randomization |
/study/{study_id}/participant/{participant_id}/randomization |
|
Visit |
/study/{study_id}/phase |
/study/{study_id}/visit |
|
/study/{study_id}/phase/{phase_id} |
/study/{study_id}/visit/{visit_id} |
|
|
Participant |
/study/{study_id}/record |
/study/{study_id}/participant |
|
/study/{study_id}/record/{record_id} |
/study/{study_id}/participant/{participant_id} |
|
|
Participant Progress |
/study/{study_id}/record-progress/steps |
/study/{study_id}/participant-progress/forms |
|
Participant Device Token |
/study/{study_id}/record/{record_id}/device-token |
/study/{study_id}/participant/{participant_id}/device-token |
|
Repeating Data |
/study/{study_id}/report |
/study/{study_id}/repeating-data |
|
/study/{study_id}/report/{report_id} |
/study/{study_id}/repeating-data/{repeating_data_id} |
|
|
Repeating Data Instance |
/study/{study_id}/record/{record_id}/report-instance |
/study/{study_id}/participant/{participant_id}/repeating-data-instance |
|
/study/{study_id}/record/{record_id}/report-instance/{report_instance_id} |
/study/{study_id}/participant/{participant_id}/repeating-data-instance/{repeating_data_instance_id} |
|
|
/study/{study_id}/report-instance |
/study/{study_id}/repeating-data-instance |
|
|
/study/{study_id}/report-instance/{report_instance_id} |
/study/{study_id}/repeating-data-instance/{repeating_data_instance_id} |
|
|
Repeating Data Data Entry |
/study/{study_id}/record/{record_id}/data-point/report/{report_instance_id} |
/study/{study_id}/participant/{participant_id}/data-point/repeating-data/{repeating_data_instance_id} |
|
/study/{study_id}/record/{record_id}/data-point/report/{report_instance_id}/{field_id} |
/study/{study_id}/participant/{participant_id}/data-point/repeating-data/{repeating_data_instance_id}/{field_id} |
|
|
Form |
/study/{study_id}/step |
/study/{study_id}/form |
|
/study/{study_id}/step/{step_id} |
/study/{study_id}/form/{form_id} |
|
|
Survey Form |
/study/{study_id}/survey/{survey_id}/survey-step |
/study/{study_id}/survey/{survey_id}/survey-form |
|
/study/{study_id}/survey/{survey_id}/survey-step/{survey_step_id} |
/study/{study_id}/survey/{survey_id}/survey-form/{survey_form_id} |