Requirements for Working with the API

To use the ClearTrial Web Services API, your client must be able to issue HTTP GET, POST, PUT, and DELETE calls. The client can be Java, .NET, Perl, Python, or a command line curl call.

• User Capabilities
  
• Stateless API
  
• Compression
  
• Security
  
• Authentication
  
• ClearTrial Resources
  
• Daily Limit for Customer Requests
  
• Representations
  

User Capabilities

To work with the ClearTrial Web Services API, you must be a licensed user who has been granted the additional role/capability Can access WS-API by the system administrator.

Note:

The Web Services capabilities are only available to licensed users. Please contact your account manager for details on subscribing to the ClearTrial Web Services API.

Stateless API

The Web Services API that the ClearTrial software exposes is stateless. This means that each call is independent of the previous call, and the information conveyed by the client in the request must be sufficient for the server to understand and act upon the request.

Compression

To decrease network bandwidth usage, if the incoming HTTP request contains the Accept-Encoding HTTP header with gzip value, the ClearTrial software compresses the contents it returns.

Security

All communication with the ClearTrial Web Services API is encrypted and secured using HTTPS connections.

Authentication

The ClearTrial Web Services API supports the Basic Access Authentication scheme.

The ClearTrial Web Services API expects that the Authorization HTTP header has already been populated with the Base64 encoding of the username and password (as described in the IETF specification) when accessing the resources. The ClearTrial Web Services API will not challenge the user by sending a WWW-Authenticate HTTP header if it detects that the Authorization HTTP header is missing.

Every request must also contain the ClearTrial Customer ID in an HTTP header named customerCode.

Here is an example of authentication using the UNIX command line tool curl:

curl --user myLogin:myPassword --header"customerCode: myCustomerCode"  --get https://cleartrial-api.oracleindustry.com/cleartrial-ws/plans/10802/siteInformation

ClearTrial Resources

The ClearTrial Web Services API exposes resources through distinct URLs and the HTTP method calls dictate the action that is required to be performed on the identified resource. ClearTrial resources include products (medical devices and drugs), studies, plans, portfolios, and other resources. The ClearTrial Web Services API refers to products as compounds.

Each resource may have zero to many sub-resources. Sub-resources make sense only within the context of the parent resource and, therefore, the sub-resource URLs use the parent resource URL as the base. Examples of resource and sub-resource URLs appear in subsequent chapters.

Daily Limit for Customer Requests

Customers are able to make no more than 500 requests per minute and no more than 10,000 requests per day using the WS-API.

Representations

Every resource has a representation. The representation appears as JSON. The user can set the Accept HTTP header in the request to application/json.

In the absence of the Accept header, the ClearTrial Web Services API returns the representation in JSON.

An example of a JSON representation appears as follows:

{
"id":"10801",
"name":"Baseline Locked Plan",
"code":"test",
"createdBy":"administrator",
"createdDate":"15-Apr-2010",
"lastModifiedBy":"administrator",
"lastModifiedDate":"15-Apr-2010",
"planState":"Draft",
"outsourcingOption":"Combination",
"startDate":"01-Apr-2010",
"preStudyStartDate":"01-Jan-2010",
"defaultModelingCurrency":"USD",
"drugHandlingType":"Room Temperature",
"radioLabeledDrug": false,
"locationsUrl":"/cleartrial-ws/plans/10801/locations",
"siteInformationUrl":"/cleartrial-ws/plans/10801/siteInformation",
"siteApprovalScheduleUrl":"/cleartrial-ws/plans/10801/siteApprovalSchedule",
"dataUrl":"/cleartrial-ws/plans/10801/data",
"subjectUrl":"/cleartrial-ws/plans/10801/subject",
"treatmentUrl":"/cleartrial-ws/plans/10801/treatment",
"monitoringInformationUrl":"/cleartrial-ws/plans/10801/monitoringInformation",
"monitoringScheduleUrl":"/cleartrial-ws/plans/10801/monitoringSchedule",
"serviceProviderUrl":"/cleartrial-ws/plans/10801/serviceProvider",
"laborUrl":"/cleartrial-ws/plans/10801/labor",
"laborMonthlyByMajorTaskUrl":"/cleartrial-ws/plans/labor?view=monthlyByMajorTask": 
"laborMonthlyByResourceUrl":"/cleartrial-ws/plans/labor?view=monthlyByResource",
"costUrl":"/cleartrial-ws/plans/10801/cost",
"costMonthlyUrl":"/cleartrial-ws/plans/cost?view=monthly",
"url":"/cleartrial-ws/plans/10801"
}

Every resource representation contains a URL property that indicates to the client the unique URL associated with that instance of the resource.

In the previous example, <url>/cleartrial-ws/plans/10801</url> , the JSON representation indicates that the plan resource whose plan ID is 10801 can always be found at that URL location.

The plan representation contains other URL properties such as locationsUrl, siteInformationUrl, siteApprovalScheduleUrl, and others. These are sub-resources under the plan resource and the URLs indicate the locations for that plan resource instance's sub-resources.

For example, the site locations for the plan resource whose ID is 10801 can be found at the URL, /cleartrial-ws/plans/10801/locations.

The curl Unix command is:

curl --user myLogin:myPassword --header "customerCode: myCustomerCode" --header"Accept: application/json" --get https://cleartrial-api.oracleindustry.com/cleartrial-ws/plans/10801/locations

Some of the APIs also allow a client to add or update resources using the HTTP PUT or POST method. For example, a client can add a new compound or product into ClearTrial at the URL: /cleartrial-ws/compounds. Assuming the content is in the file postContent, the curl Unix command is:

cat postContent | curl --user myLogin:myPassword --header "customerCode: myCustomerCode" --header"Content-Type: application/json" --request PUT https://cleartrial-api.oracleindustry.com/cleartrial-ws/compounds