INFO: Best Practices on Using REDCap's API Methods

REDCap is a secure application supported by Mass General Brigham, Research Information Science & Computing (RISC) Applications Team. Mass General Brigham REDCap has all the necessary physical and operational securities in place to meet or exceed Federal and State security and privacy regulations for data transmission and storage. 

Using MGB or External User Accounts for API:

To request access to the REDCap API:

  1. Request API Token access within the REDCap project
  2. Review these power point slides: REDCap API Training

The API, Application Programming Interface, is a tool for controlling data flow in and out of your REDCap project. It is important to note that the use of the API must be managed by a well understood plan that outlines why, how, and when a project’s data is going to be accessed. A well-established plan will indicate whether there is a need for using REDCap’s API. The need for using the API must come from the task or workflow at hand. The API should not be used as a first go-to alternative. One key aspect that must be understood is that every API call is equivalent to a user accessing the REDCap services. While REDCap services have been optimized to support the expected workload from REDCap users, incorrect usage or over-usage of the REDCap API can create unnecessary and unexpected load on the system and affect overall performance. The API is typically meant to automate time-consuming tasks or tasks that require data to be exported to other systems. For example:

  • Importing 1000 files manually through REDCap Import application can take a user many days to complete. REDCap’s API can be used to automate this task and free a user’s time. REDCap services can be affected if each import file contains millions of data points.
  • Interfacing with REDCap to determine the number of current records in a project can be done through the API. In this case, using the API to count the total number of records every single second can make the system slow and unresponsive.
  • Exporting files attached to a record in a given field for many records can be time-consuming for a user. The API can be used to automate this task. However, the amount of resources needed is determine by the number and size of the files to be exported.

In each of these simple use-cases the REDCap services are taxed and it can lead to performance issues. Once the need for using the API has been highlighted by the task it is important to understand how and when the API call needs to be made without disrupting REDCap services. In short, there are three types of API methods available through REDCap: API methods for importing, exporting, and deleting. Each method should be used according to best practices for ensuring: data security, and proper use of REDCap resources. It is important to note that when data is exported out of REDCap it is up to the user to secure that data. Safeguards that exist within the REDCap system are no longer applied once the data is exported. Additionally, deleting data should be done with the utmost of care as no confirmation messages will be prompted to the user when deleting data via the API.

Using Service Accounts for API:

To use a service account to make API Calls please complete the following:

  • Service Account needs to be registered and managed by CyberArk 
  • Review these power point slides: REDCap API Security Training
  • Log into REDCap at least once using the Service Account credentials 
  • Request API token access within the REDCap project, logged in as the service account   

The token will be unique to the service account. 

Additional Resources

REDCap API Documentation
REDCap Getting Started
Log in to MGB REDCap

About REDCap

Go to KB0035159 in the IS Service Desk

Related articles