1. OKEC REST APIREST API for Knowledge Management with the Redwood User Experience
  2. Quick Start

Quick Start

You can make many types of HTTP requests using Oracle Applications Cloud 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.

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.

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. A Service 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: 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 articles resource. 

api/knowledge-management/v2/articles

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/api/knowledge-management/v2/articles

Depending on your business requirements, you might want to configure Cross-Origin Resource Sharing (CORS) now to fine-tune the REST API behavior. 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 OAuth 2.0 for token-based authentication and authorization. To work with REST API for Knowledge Management with the Redwood User Experience, you need an OAuth token from the supported identity service provider Oracle Cloud Infrastructure Identity and Access Management (IAM).

For detailed information on adding a confidential application, configuring your client, authentication, and authorization, see Configure OAuth Using the Fusion Applications Identity Domain.

Authorization

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

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

Step 5: Send an HTTP Request

You can use a client of your choice, or a third-party client such as Postman, or cURL to obtain the access token and pass it to access the required resources.

Example: Using cURL to access a resource

Here's a cURL request:

curl -H "Authorization: Bearer Token" \
-X GET https://servername.fa.us2.oraclecloud.com/api/knowledge-management/v2/articles
-H 'Content-Type: application/json'

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": "9285C4D829CD468AB39C49907A1ED3E4",
            "versionId": "A14CCD4BB3404281939635ABEA458ECB",
            "documentId": "AUTO1",
            "title": "Document with attachment updated123.",
            "version": "2.0",
            "answerId": 10027037,
            "dateModified": "2022-04-25T16:32:21.000+00:00",
            "displayStartDate": "1900-01-01T00:00:00.000+00:00",
            "displayEndDate": "9999-12-31T00:00:00.000+00:00",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://servername.fa.us2.oraclecloud.com/api/knowledge-management/v2/articles/9285C4D829CD468AB39C49907A1ED3E4",
                    "mediaType": "application/json, application/xml",
                    "method": "GET"
                },
                {
                    "rel": "collection",
                    "href": "https://servername.fa.us2.oraclecloud.com/api/knowledge-management/v2/articles",
                    "mediaType": "application/json, application/xml",
                    "method": "GET"
                }
            ],
            "versionState": "LIVE",
            "createDate": "2022-04-25T15:06:17.000+00:00",
            "lastModifiedDate": "2022-04-25T15:06:17.000+00:00",
            "dateAdded": "2022-04-25T16:32:20.000+00:00",
            "published": true,
            "pending": false,
            "publishDate": "2022-04-25T16:32:20.000+00:00",
            "checkedOut": false,
            "publishedVersion": "2.0",
            "isForEdit": false
        },
        {
            "recordId": "2F33BD8C1D9246B9970D0D098C2BA17F",
            "versionId": "FFC350D9AA7E40D58A664E38FC1E2751",
            "documentId": "FAQ212",
            "title": "Registration now open for Oracle OpenWorld.",
            "version": "2.0",
            "answerId": 10027036,
            "dateModified": "2022-04-25T19:53:22.000+00:00",
            "displayStartDate": "1900-01-01T00:00:00.000+00:00",
            "displayEndDate": "9999-12-31T00:00:00.000+00:00",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://servername.fa.us2.oraclecloud.com/api/knowledge-management/v2/articles/2F33BD8C1D9246B9970D0D098C2BA17F",
                    "mediaType": "application/json, application/xml",
                    "method": "GET"
                },
                {
                    "rel": "collection",
                    "href": "https://servername.fa.us2.oraclecloud.com/api/knowledge-management/v2/articles",
                    "mediaType": "application/json, application/xml",
                    "method": "GET"
                }

Example: Using Postman to access a resource

This is how the request looks in Postman:

This image shows a Postman request.

In Postman, the results are formatted and displayed in the Response section. You can you view the response in multiple formats. This screenshot shows the response in JSON.This figure shows how a response body in JSON format looks in Postman.

Congratulations! Now you're ready to do more with your REST APIs. Join the Oracle Developer Community, where you can share tips and advice with others.