{"id":19713391,"url":"https://github.com/ctsit/redcap_webservices","last_synced_at":"2025-08-27T13:14:46.399Z","repository":{"id":49493330,"uuid":"122547594","full_name":"ctsit/redcap_webservices","owner":"ctsit","description":"REDCap external module that provides a way to expose SQL query results to the external world.","archived":false,"fork":false,"pushed_at":"2021-06-16T14:38:56.000Z","size":470,"stargazers_count":3,"open_issues_count":2,"forks_count":6,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-05T18:52:08.272Z","etag":null,"topics":["redcap","redcap-external-module","redcap-repo"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ctsit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-22T23:23:49.000Z","updated_at":"2024-08-21T09:39:26.000Z","dependencies_parsed_at":"2022-09-12T11:10:13.317Z","dependency_job_id":null,"html_url":"https://github.com/ctsit/redcap_webservices","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fredcap_webservices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fredcap_webservices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fredcap_webservices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fredcap_webservices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ctsit","download_url":"https://codeload.github.com/ctsit/redcap_webservices/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251559857,"owners_count":21609089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["redcap","redcap-external-module","redcap-repo"],"created_at":"2024-11-11T22:21:43.083Z","updated_at":"2025-04-29T18:31:13.452Z","avatar_url":"https://github.com/ctsit.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# REDCap Web Services\nProvides a way to expose SQL query results to the external world.\n\n## Motivation\nThe motivation of this project is the use case where an external website needs to display statistics of a given REDCap project or a REDCap system. A solution for that is to give the client an endpoint that returns a JSON containing the results of a SQL query. SQL queries are statically defined within the web service to allow admins to verify queries are written to only return summary data with no risk of exposing sensitive data.\n\n## Prerequisites\n- REDCap \u003e= 8.0.3\n\n## Installation\n- Clone this repo into to `\u003credcap-root\u003e/modules/redcap_webservices_v\u003cversion_number\u003e`.\n- Go to **Control Center \u003e External Modules** and enable REDCap Web Services.\n\n## How to use it\n\n### Configuration form\nTo register your SQL queries, go to **Control Center \u003e External Modules** and click on REDCap Web Services configure button. Here is an example of a working configuration:\n\n![Configuration form](img/config-form.png)\n\n### Endpoints page\n\nThe resulting list of endpoints can be seen at **Control Center \u003e REDCap Web Services**:\n\n![Configuration form](img/webservices-list.png)\n\n\n### Response examples\n\nHere is an example of a successful response from endpoint `test` defined, in the example above:\n\n``` json\n{\n    \"success\": true,\n    \"data\": [\n        {\n            \"project_id\": \"13\"\n        }\n    ]\n}\n```\n\nHere is the response when the user credentials are not provided:\n\n``` json\n{\n    \"success\": false,\n    \"error_msg\": \"Missing user.\"\n}\n```\n\nHere is the response when a required parameter is not specified in the URL:\n\n``` json\n{\n    \"success\": false,\n    \"error_msg\": \"Missing param 'name'.\"\n}\n```\n\nThere are other error handlings available, which are not shown on these examples.\n\n## Features included\n\n### Parameterized SQL queries\nYou may provide parameters to your SQL queries by using the pattern `:param`, e.g. `(...) WHERE project_name = :name`. The parameters are required in the endpoint URL query, e.g. `https://yourEndpoint?(...)\u0026name=project_test`.\n\n#### Project ID parameter\nIf you specify a `:pid` parameter in your query, the service will only work for projects that have REDCap Web Services enabled. It is a good way to restrict the service scope.\n\n__Important:__ To avoid SQL injection, every non numeric parameter provided is quoted by this module. So __do not quote your parameters__, no matter if it is a string or not. For example, the following query won't work properly: `(...) WHERE project_name = \":name\"`.\n\n### Basic access authentication\nIf your queries return sensitive information, username and password can be provided as a security mechanism. If the credentials are set, the caller must use [Basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) on the requests. In this case, it is highly recommended to make the requests over HTTPS.\n\nHere is an example of how to test your endpoint with authentication using CURL (user `test`, password `123`):\n\n``` shell\n$ curl --user test:123 '\u003cYOUR_ENDPOINT_URL\u003e'\n```\n\nUsing AJAX (unsafe for public applications):\n\n``` javascript\n$.ajax({\n    url: '\u003cYOUR_ENDPOINT_URL\u003e',\n    headers: { 'Authorization': 'Basic ' + btoa('test:123') }\n}).success(function(data) {\n    // Do stuff.\n});\n```\n\n### SQL syntax errors on response\nIf some SQL query returns an error, you may output a detailed error message in the JSON response by enabling the flag \"Expose SQL error on response\". Be careful, since error messages can expose details about your query. This feature is useful for testing purposes.\n\n### Additional query examples\n\nHere are some examples of queries that produce deidentified summary data that could be used to measure the data collection effort of a study\n\n* Return the record for a project identified by its project_id\n\n```\nrecord_count\nfrom redcap_record_counts\nwhere project_id = :project_id\n```\n\nReturns\n\n```\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"record_count\": \"25\"\n    }\n  ]\n}\n```\n\n* Count the number of study participants at each site on a project specified by \"pid\"\n\n```\nvalue, rcdag.group_name, count(*) as qty\nfrom redcap_data as rcd\ninner join redcap_data_access_groups as rcdag on (rcd.value = rcdag.group_id)\nwhere field_name = \"__GROUPID__\" and rcd.project_id = :pid\ngroup by value\n```\n\nReturns\n\n```\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"value\": \"1\",\n      \"group_name\": \"FSU\",\n      \"qty\": \"2\"\n    },\n    {\n      \"value\": \"2\",\n      \"group_name\": \"UF\",\n      \"qty\": \"2\"\n    }\n  ]\n}\n```\n\n* Show the number of new informed consents by week\n\nAssuming the date of every informed consent form is recorded in a REDCap field identified by \"consent_date_field\" and a project is identified by \"pid\" you could group the dates of consent by week with this query\n\n```\nconcat_ws(\"-\", year(value), week(value)) as icf_week, count(*) as qty\nfrom redcap_data as rcd\nwhere field_name = \":consent_date_field\" and rcd.project_id = :pid\ngroup by icf_week\norder by icf_week asc\n```\n\nReturns\n\n```\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"icf_week\": \"2017-49\",\n      \"qty\": \"1\"\n    },\n    {\n      \"icf_week\": \"2017-50\",\n      \"qty\": \"12\"\n    },\n    {\n      \"icf_week\": \"2017-51\",\n      \"qty\": \"3\"\n    },\n    {\n      \"icf_week\": \"2018-0\",\n      \"qty\": \"1\"\n    },\n    {\n      \"icf_week\": \"2018-1\",\n      \"qty\": \"1\"\n    },\n    {\n      \"icf_week\": \"2018-2\",\n      \"qty\": \"1\"\n    }\n  ]\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctsit%2Fredcap_webservices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fctsit%2Fredcap_webservices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctsit%2Fredcap_webservices/lists"}