1. OKEC REST APIREST API for Knowledge Management in Oracle Fusion Service
  2. Quick Start

Quick Start

You can make many types of HTTP requests using Fusion Applications REST APIs. You can easily make requests to view, create, update, or delete content records. As an example, let's look at how to send a simple REST HTTP request to find and retrieve the list of documents that are published after a specified date for the Content resource.

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.

Review Roles and Privileges: You must have the necessary security roles and privileges to use the GET, POST, PATCH, and DELETE methods on your parent and child resources.

Review opt-in requirements. Some resources of their attributes may be associated with features that require opt-in before you can use them. You must make sure that you enable opt-in features before you start.

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. To help you choose one, see Work with your REST Client.

Step 2: Get Your Fusion Applications Account Info

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

  • REST Server URL. Typically, this is the URL of your Oracle Cloud service. For example, https://servername.fa.us2.oraclecloud.com
  • User name and password. An Engagement Cloud user with permissions to access the services 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.

  1. 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 resource you're working with. You can pick any endpoint in All REST Endpoints. In our example, we're interested in the content resource. 

    /km/api/latest/content

    Combine the REST Server URL and, in this example, the content resource path and your request URL is complete. For more information, see URL Paths. 

    https://servername.fa.us2.oraclecloud.com/km/api/latest/content
  2. 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 command as follows: 

-u "username:password"

In a client such as Postman, you enter the user name and password in the Authorization tab. This screenshot shows how to specify this information in Postman:

This figure shows how to use Basic Authorization for authorization in Postman.

If you're not familiar with any of the syntax used in the example, check out Work with your REST Client.

If you're an advanced REST user, but are reading our Quick Start anyway, you want to configure Cross-Origin Resource Sharing (CORS) now. Otherwise, you're ready to move on to Step 4.

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, Fusion Applications 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).

  • JWT in the HTTP header over SSL, which extracts the user name from the JWT 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 POST https://servername.fa.us2.oraclecloud.com/km/api/latest/content 
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" 
-H "Accept: application/json" -H "Content-Type: application/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 -X POST https://servername.fa.us2.oraclecloud.com/km/api/latest/content 
-u "username:password" -H "Accept: application/json" 
-H "Content-Type: application/json"

Your authorization and authentication information gets passed in the Authorization key of the request header. When passing tokens (SAML or JWT) in Postman, the Authorization key must include Bearer, followed by the token, as shown in this screenshot:

This figure shows how to use bearer token for authorization in the Postman client.

Authorization

You can access the restricted knowledge information from the repository only with proper authorization. For more information about users and roles, see Using Knowledge Management.

Note:

After authentication, you can access the public knowledge content and public REST APIs for Knowledge in Fusion Service, without authorization or anonymously. To access the REST APIs and content anonymously, send the REST request without any authorization headers.

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, you want to get the list of documents that are published after 01-Jan-2014 using the Content resource. You can do this using the describe action in cURL:

curl -X GET https://servername.fa.us2.oraclecloud.com/km/api/latest/content?limit=10&q=publishDate+after+%272014-04-01%27&mode=key 
-u "username:password" -H "Accept: application/json" 
-H "Content-Type: application/json"

This is how the request looks in Postman:

This figure shows how a sample GET request looks like in Postman.

If the request is successful, you receive a response with a body, abbreviated here to save space. 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 clients, review the failure Status Codes, and then try again. 

{
"recordId": "048016517ab56ef014519740375005599",
"versionId": "048016517ab56ef01451974037500544f",
"documentId": "OR4",
"title": "Registration Now Open to the Public for Oracle OpenWorld San Francisco",
"version": "2.0",
"answerId": 1000077,
"links": [
{
"rel": "canonical",
"href": "https://<REST_API_HOST>/km/api/latest/content/048016517ab56ef014519740375005599",
"mediaType": "application/json, application/xml",
"method": "GET"
},
{
"rel": "collection",
"href": "https://<REST_API_HOST>/km/api/latest/content",
"mediaType": "application/json, application/xml",
"method": "GET",
"profile": "https://<REST_API_HOST>/km/api/latest/metadata-catalog/content"
}
]
}

In a client such as Postman, the results are formatted and displayed in the Response section. For example, Postman lets you view the output in multiple formats. This screenshot shows the response in JSON.

This figure shows how a response body in JSON format looks inPostman.

Congratulations! Now you're ready to do more with your REST APIs.