| Oracle® Health Sciences ClearTrial Cloud Service Web Services API User Guide Release 5.4 E63098-01 |
|
 Previous |
 Next |
| Oracle® Health Sciences ClearTrial Cloud Service Web Services API User Guide Release 5.4 E63098-01 |
|
Previous |
Next |
The ClearTrial Web Services API is a simple and powerful web services interface into the ClearTrial software. It is a HTTP-based API that is technology and platform independent. The API is hosted at: https://cleartrial-api.oracleindustry.com/cleartrial-ws.
To use the ClearTrial Web Services API, the 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.
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. |
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.
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.
All communication with the ClearTrial Web Services API is encrypted and secured using HTTPS connections.
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
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, actuals, 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.
The ClearTrial Web Services API also supports reading and writing ClearTrial Track data in and out of the ClearTrial software. The resources supported for the Clear Trial Track application include sites, subjects, and monitoring.
Every resource has a representation. The representation can appear as XML or JSON, according to user preference. The user can set the Accept HTTP header in the request to either application/xml or application/json, respectively.
In the absence of the Accept header, the ClearTrial Web Services API returns the representation in JSON.
An example of an XML representation of a plan resource appears as follows:
<plan>
<id>10801</id>
<name>Baseline Locked Plan</name>
<code>test</code>
<createdBy>administrator</createdBy>
<createdDate>15-Apr-2010</createdDate>
<lastModifiedBy>administrator</lastModifiedBy>
<lastModifiedDate>15-Apr-2010</lastModifiedDate>
<planState>Draft</planState>
<outsourcingOption>Combination</outsourcingOption>
<startDate>01-Apr-2010</startDate>
<preStudyStartDate>01-Jan-2010</preStudyStartDate>
<defaultModelingCurrency>USD</defaultModelingCurrency>
<drugHandlingType>Room Temperature</drugHandlingType>
<radioLabeledDrug>false</radioLabeledDrug>
<locationsUrl>/cleartrial-ws/plans/10801/locations</locationsUrl>
<siteInformationUrl>/cleartrial-ws/plans/10801/siteInformation
</siteInformationUrl>
<siteApprovalScheduleUrl>/cleartrial-ws/plans/10801/siteApprovalSchedule
</siteApprovalScheduleUrl>
<dataUrl>/cleartrial-ws/plans/10801/data</dataUrl>
<subjectUrl>/cleartrial-ws/plans/10801/subject</subjectUrl>
<treatmentUrl>/cleartrial-ws/plans/10801/treatment</treatmentUrl>
<monitoringInformationUrl>/cleartrial-ws/plans/1001/monitoringInformation
</monitoringInformationUrl>
<monitoringScheduleUrl>/cleartrial-ws/plans/10801/monitoringSchedule
</monitoringScheduleUrl>
<serviceProviderUrl>/cleartrial-ws/plans/10801/serviceProvider
</serviceProviderUrl>
<laborUrl>/cleartrial-ws/plans/10801/labor</laborUrl>
<laborMonthlyByMajorTaskUrl>/cleartrial-ws/plans/10801/
labor?view=monthlyByMajorTask</laborMonthlyByMajorTaskUrl>
<laborMonthlyByResourceUrl>/cleartrial-ws/plans/10801/
labor?view=monthlyByResource</laborMonthlyByResourceUrl>
<costUrl>/cleartrial-ws/plans/10801/cost</costUrl>
<costMonthlyUrl>/cleartrial-ws/plans/10801/cost?view=monthly
</costMonthlyUrl>
<url>/cleartrial-ws/plans/10801</url>
</plan>
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 examples, <url>/cleartrial-ws/plans/10801</url> and "url": "/cleartrial-ws/plans/10801," in the XML and JSON representations, respectively, indicate 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
To obtain the XML representation, change the Accept header value in the previous command to:
"Accept:application/xml"
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
To use the XML representation, change the Content-Type header value in the command above to:
"Accept:application/xml"
The following HTTP error codes may be returned for the reasons as follows:
400 - missing customerCode header
401 - wrong customerCode
401 - incorrect/missing credentials
403 - credentials provided do not have the necessary permissions required for access
404 - incorrect URL used
The following chapters describe the ClearTrial Web Services APIs, grouped by ClearTrial resources, and the ClearTrial Track API. In the URLs shown, values within braces {} are placeholders for entering the ID of a specific instance of the resource.
For example, in /cleartrial-ws/studies/{studyID}, the {studyID} is a placeholder for any study IDs identified in the <id> elements in the representation returned by the GET call to /cleartrial-ws/studies.
Each ClearTrial Web Services API specification includes the following information:
Purpose
Method: GET or PUT
The URL to which the call is made
Sample output in JSON for a late-stage study
Sample output in XML for a late-stage study
Sample output in JSON for a Phase I Healthy Volunteers study, if it differs from a late-stage study
Sample output in XML for a Phase I Healthy Volunteers study, if it differs from a late-stage study
This section provides guidelines and recommendations for using and developing against the REST Web Services API published by ClearTrial. The following are recommended practices for secure usage of this API.
Developers working with the REST API are subject to the same roles and permissions required to use ClearTrial applications. To work with the REST API, developers must have the Web Services API permission.
The REST API supports application/XML and application /JSON. Developers must use one of these MIME types in the Accept and Content-Type HTTP headers. Otherwise, the API will reject the requests.
To prevent SQL injections, the REST API uses bind variables in SQL queries that might involve any user input.
The data that the REST API returns is properly encoded for their returned types, either XML or JSON. Developers should encode data based on the context they are using. The REST API does not know the context, so safeguards are important.
The REST API is stateless and, therefore, does not create and maintain an HTTP session. Therefore, the typical security issues associated with HTTP sessions do not apply.
However, the API does require transmission of the username and password in the HTTP authorization header. Developers, therefore, should ensure that the username and password are stored securely and use the HTTPS protocol. For example, this might be the Oracle Platform Security Services (OPSS) framework.
The API validates input from developers before using it. For outbound data from the REST API, developers are responsible for properly encoding the data, depending on the context where the data is being used.
The REST API ensures that the invoker has the permissions to access every requested resource and representation or entity returned.
The username and password are the only business-agnostic data that is considered sensitive for the REST API. The data is transmitted over HTTPS and is never at rest; that is, it is not stored or output to log files. Developers should also provide safe and secure storage when data is at rest.
The REST API ensures that the invoker has the permissions to access every requested resource and representation or entity returned.
Because the REST API is stateless, there is no HTTP session to exploit via Cross-Site Request Forgery (CSRF). Every request needs to carry the Authorization header with valid values; otherwise, it is rejected.
