Frequently Asked Questions (FAQs)

What are the differences between using client credentials and a password grant to generate a client ID and secret?

Use Password Grant when an end-user Oracle Life Sciences IAMS account will be used to make the API calls. Use Client Credentials for automated system-to-system API calls, where an actual end-user isn't necessarily involved long term. With client credentials, the password is not actually used to authenticate the API call.

For step-by-step instructions on how to generate a client ID and secret, see Generate a client ID and secret. For details about authentication on each type of client, see Get a token for authentication.

What options can I use to invoke cURL?

This table summarizes the cURL options used in the command examples. For example, here's how a code line would look like in cURL:

curl -i -X GET -u <username>:<password> -H <request-header>:<value> https://<subdomain>.<domain>.com/<path>/<resource-path>

cURL Option	Description
-d, --data @file.json	Identifies the file that contains the request body, in JSON format, on the local machine. Alternatively, you can pass the request body with -d"{id=5,status='OK'}.
-F, --form @file.json	Identifies form data, in JSON format, on the local machine.
-H --header, -I -include, and -X --request <method>	Defines one or both of the following: Content type of the request document
-i	Displays response header information.
-X	Indicates the type of request (for example, GET, POST).

What are some examples of API requests for Oracle Clinical One Platform?

After you set up your REST client, you can send a request to ensure that your connection works. For example, suppose you want to create multiple data elements for a subject. You can use the following request:

{   "type":"object",
"properties":{ "context":{ "$ref":"#/components/schemas/Context" }, "dataElements":{ "type":"array", "items":{ "$ref":"#/components/schemas/CoreDataElement" } } } }

If the request is successful, then you should receive a 200 response with a body such as the following:

{    
"type":"array",
"items":{
    "$ref":"#/components/schemas/DataElementDto20"
}
}

Do I have to request a token every time I need to make an API call?

No, you don't have to request a new token every time you make an API call. However, do keep in mind that a token is valid for 10 minutes. If you plan on making numerous API calls throughout the day, you'll have to generate a new token every 10 minutes.

How do I construct my URL for sending requests?

Use the following guidelines when sending requests using the Oracle Clinical One Platform REST API.

URL Structure

Access the Clinical One REST resources using the following URL structure:

https://<subdomain>.<domain>.com/<resource-path>

Where:

<subdomain>.<domain>.com is the host where the Oracle Clinical One Platform APIs are running.
<resource-path> is the relative path that defines the resource. For a complete list of resources and the paths for each, see All REST Endpoints.

Supported Methods

You can perform basic CRUD operations (create, read, update, and delete) on Oracle Clinical One Platform APIs using the standard HTTP method requests GET, PUT, POST, and DELETE.

Media Types

The APIs currently support only the application/JSON media type.

Supported Headers

Oracle Clinical One Platform REST APIs support only the Content-Type header to be passed in the header section of the HTTP request or response. The value for this header is specific to each API endpoint.

Compression

Use of compression on the Oracle Clinical One Platform REST APIs resource request and response is not supported at this time.

What are the status codes for an API call?

When you call any of the Oracle Clinical One Platform REST resources, the Response header returns one of the standard HTTP status codes defined in the following table:

HTTP Status Code	Description
`200 OK`	The request was completed successfully A 200 status is returned for a successful `GET` or `POST` method.
`201 Created`	The request was fulfilled and resulted in a new resource being created. The response includes a `Location` header which contains the canonical URI for the newly created resource. A 201 status is returned from a synchronous resource creation or an asynchronous resource creation that completed before the response was returned.
`202 Accepted`	The request was accepted for processing, but the processing has not been completed. The request may or may not eventually be acted upon, as it may be disallowed at the time processing actually takes place. When specifying an asynchronous (`__detached=true`) resource creation (for example, when deploying an application), or update (for example, when redeploying an application), a 202 is returned if the operation is still in progress. If `__detached=false`, a 202 may be returned if the underlying operation does not complete in a reasonable amount of time. The response contains a Location header of a job resource that the client should poll to determine when the job has finished. It also returns an entity that contains the current state of the job
`400 Bad Request`	The request could not be processed because it contains missing or invalid information (such as a validation error on a parameter or a missing required value).
`401 Unauthorized`	The request is not authorized. The authentication credentials included with this request are missing or invalid.
`403 Forbidden`	The user can't be authenticated. The user does not have authorization to perform this request.
`404 Not Found`	The request includes a resource URI that does not exist.
`405 Method Not Allowed`	The HTTP verb specified in the request (`DELETE`, `GET`, `POST`, `PUT`) is not supported for this request URI.
`406 Not Acceptable`	The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request. For example, the request's Accept header is set to XML but the operation only returns JSON.
`415 Unsupported Media Type`	The client's Content-Type header is not correct (for example, the client attempts to send the request in XML, but the resource can only accept JSON).
`500 Internal Server Error`	The server encountered an unexpected condition that prevented it from fulfilling the request.
`503 Service Unavailable`	The server is unable to handle the request due to temporary overloading or maintenance of the server. The <ProductName> REST service is not currently running.