1.2 RESTful URLs

In the context of REST for clinical research using OpenClinica, we can conceptually think of an electronic case report form (CRF) as a resource that is essentially a bunch of metadata modeled in CDISC ODM with OpenClinica extensions. Other OpenClinica objects (such as study definitions) can also be resources exposed in a RESTful manner.

About REST and Clinical Data Keys

In REST, resources are identified by logical URLs and are the key element of RESTful design. Interaction is stateless.

ClinicalData Objects (i.e. Study Subjects and their CRF data) in OpenClinica can be addressed by using ODM-based Clinical Data Keys (https://docs.openclinica.com/3.1/technical-documents/openclinica-and-cdi...)  as part of a URL path appended to /ClinicalData/, as follows:

GET /OpenClinica/ClinicalData/{format}/{mode}/ODM_XML_PATH?OPTIONS

Implementation in 3.1.3

The initial implementation of RESTful URLs in OpenClinica 3.1.3 supports a URL to return a read-only EventCRF with its associated FormData in HTML format. Only HTML format and view mode is implemented in OpenClinica 3.1.3. The general format of the URL is:

/OpenClinica/ClinicalData/html/view/{StudyOID}/{StudySubjectKey}/{StudyEventDefOID}[{StudyEventRepeatKey}]/{FormDefOID}?tabId={sectionNum} 

The URL query string options supported for this URL are tabId & exitTo:

  • tabId – the CRF section number to show (HTML format only).
  • exitTo – URL for where the 'exit' button should take the user (optional, HTML format only, relative to the OpenClinica root URL). 

An example would be:

GET /OpenClinica/ClinicalData/html/view/S_CPCS/320999/SE_CPCS[1]/F_CPCS_1?tabId=1&exitTo=ViewStudySubject?id=1

These URLs do not support OAuth security authentication.

Future Implementation Plans

The {format} component of the URL may be ‘html’ or ‘xml’. XML provides CDISC ODM XML. If omitted use CDISC ODM XML 

The {mode} component may be ‘view’, ‘edit’, or ‘print’ (html format only). 

The path builds an address to the resource. In the example above, the path ends at the Form OID level so we can determine the resource we’re looking at an EventCRF. It could go further down to the ItemGroup or Item level. The format of what’s returned and the available options may vary based on the level of the resource – addressing an EventCRF may be consumed differently than addressing an Item.

The full form of the URL would be:

GET /OpenClinica/ClinicalData/{format}/{mode}/{StudyOID}/{StudySubjectKey}/{StudyEventDefOID}[{StudyEventRepeatKey}]/{FormDefOID}?tabId={sectionNum}&exitTo={exitURL}

This page is not approved for publication.