REST API for Taleo Learn Cloud Service

Quick Start

You can make many types of HTTP requests using Oracle REST APIs. You can easily make requests to view, create, update, or delete records. But, let's first send a simple REST HTTP request to find out the structure of an Announcement object.

User REST API provides programmatic access to user data in Learn instance.

Step 1: Consider Before You Start

Review the basics. If you're new to REST APIs, make sure you understand the basics of REST and JSON, and scan our list of important terms.

Choose a client. REST APIs connect software programs over the HTTP protocol. You need a software client to send the HTTP requests. In our examples, we use cURL. But, cURL isn't the only tool you can use.

Step 2: Get Your Oracle Applications Cloud Account Info

To make a REST HTTP request, you need to gather a few bits of information:

REST Server URL. Typically, the URL of your Oracle Cloud service. For example, https://servername.fa.us2.oraclecloud.com.
User name and password. An Oracle Cloud service user with permissions to access the resources you're using.

You can find the REST Server URL, user name, and password in the welcome email sent to your Oracle Cloud service administrator.

Step 3: Configure Your Client

With the information gathered so far, you're ready to configure your client to send a REST HTTP request.

Construct the request URL. The URL consists of the server name and the resource path:
```
https://<server>/<resource-path>
```
The <server> is the REST Server URL from Step 2, as in:
```
https://servername.fa.us2.oraclecloud.com
```
The <resource-path> is the relative path or endpoint to the REST resource you're working with.
```
/learn.rest/resources/11.13.18.05/Catalog
```
Combine the REST Server URL and, in this example, the Catalog REST resource path and your request URL is complete.
```
https://servername.fa.us2.oraclecloud.com/learn.rest/resources/11.13.18.05/Catalog
```
Provide your account information. Include your user name and password (from Step 2) in the client. For example, if you are using cURL, you can specify your account information using the -u cURL command as follows:
```
-u <username:password>
```
Set the media type. Media type defines the structure of the HTTP payloads exchanged between the server and the client. For example, if you're using cURL, you can specify a resource item media type using the header -H command as follows:
```
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'
```
For more on media types, see Supported Media Types.

When you're done, the complete cURL command should look like this:

curl -u <username:password> \
 -X GET https://servername.fa.us2.oraclecloud.com/learn.rest/resources/11.13.18.05/Catalog/describe HTTP/1.1 \
 -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'  | json_pp

Step 4: Authenticate and Authorize

Now that you've configured the client with a complete request URL, it's time to authenticate and authorize yourself. Authentication proves that your credentials are genuine, and authorization allows you to apply your access privileges.

Authentication

To make sure data access over a network is secure, Oracle REST APIs use a global Oracle Web Services Manager (OWSM) security policy called Multi Token Over SSL RESTful Service Policy (oracle/multi_token_over_ssl_rest_service_policy). This security policy enforces the following authentication standards:

Basic authentication over SSL (Secure Socket Layer), which extracts the user name and password credentials from the HTTP header.
SAML 2.0 bearer token in the HTTP header over SSL , which extracts a SAML 2.0 bearer assertion (XML security token).

You must select one of the standards. Let's look at our example using Basic authentication over SSL. To authenticate, you must submit the user name and password for your Oracle Cloud account. Typically, the user name and password are encoded in Base64 format, as in:

curl \
-X GET https://servername.fa.us2.oraclecloud.com/learn.rest/resources/11.13.18.05/Catalog/describe HTTP/1.1 \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

Alternatively, you can use the -u cURL option to pass the user name and password for your Oracle Cloud account, as in this example:

curl -u username:password \
-X GET https://servername.fa.us2.oraclecloud.com/learn.rest/resources/11.13.18.05/Catalog/describe \
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

Authorization

Authorization enforces access privileges by service role. Access to an object determines access to a REST resource. So, make sure that your user has the proper role.

For additional details, including a list of specific roles for accessing a REST resource, see Security Reference for Common Features.

Example - Step 5: Send an HTTP Request

You're almost done. Now that your authentication and authorization are set, you're ready to send a test HTTP request. Continuing with our example, we want to get all the information about the structure of the Catalog object in REST. You can do this using the describe action in cURL:

curl -u username:password \
 -X GET https://servername.fa.us2.oraclecloud.com/learn.rest/resources/11.13.18.05/Catalog/describe \
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

If your request for information about the Catalog object is successful, you receive a response with a body similar to the following abbreviated example. If your request fails, and you're using cURL, review the response comments, adjust your request, and then try again. If you're using other REST clients, review the failure Status Codes, and then try again.