REST API for Knowledge Advanced in B2C Service

Quick Start

You can make many types of HTTP requests using Oracle B2C Service Knowledge Advanced REST APIs. You can easily make requests to view, create, update, or delete content objects. But, let's first send a simple REST HTTP request to find and retrieve the list of documents that are published after a specified date for the Content REST 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 or 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 REST 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 Oracle B2C Service Knowledge Advanced 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 B2C Service Knowledge Advanced server. For example, https://site.example.com
User name and password. An Oracle B2C Service Knowledge Advanced 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 B2C Service Knowledge Advanced 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://site.example.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. For 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://site.example.com/km/api/latest/content
```
Provide your account information. Include your user name and password (from Step 2) in the client.

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

curl -X POST  https://site.example.com/km/api/latest/auth/integration/authorize -H "Accept: application/json" -H "Content-Type: application/json" -H "kmauthtoken: {"siteName":"example_site"}" -d "{"login": "user_name", "password": "passWorD", "siteName": "example_site"}"

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 Auth for authorization in the Postman client.

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

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. If you are a staff account or contact user, you can use OAuth 2.0 framework for authorization. For more information, see Authenticating and Authorizing the Staff Account or the Contact User using OAuth 2.0 section in Authenticate and Authorize.

Authentication

To make sure data access over a network is secure, Oracle B2C Service Knowledge Advanced REST APIs use HTTP Basic Authentication for authenticating users and a custom token or OAuth 2.0 framework for authorizing users.

Let's look at our example using Basic authentication over SSL. To authenticate, you must submit the user name and password for your Oracle B2C Service Knowledge Advanced account. You must also specify the site name along with the credentials and also in a custom token called kmauthtoken as shown in the following example. Typically, the user name and password are encoded in Base64 format, as in:

curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" -X POST https://sitename.example.com/km/api/latest/auth/integration/authorize -H "Accept: application/json" -H "Content-Type: application/json" -H "kmauthtoken: {"siteName":"example_site"}" -d "{  "siteName": " example_site "}"

Alternatively, you can use the -d cURL option to pass the user name, password, and site name for your Oracle B2C Service Knowledge Advanced account, as in this example:

curl -X POST  https://site.example.com/km/api/latest/auth/integration/authorize -H "Accept: application/json" -H "Content-Type: application/json" -H "kmauthtoken: {"siteName":"example_site"}" -d "{"login": "user_name", "password": "passWorD", "siteName": "example_site"}"

If the authentication is successful, a custom token called authenticationToken is returned as shown in the following example.

{ authenticationToken:"+lOR60Szzpk+3aiBn2uJ3BSqBrT79DaIVoC8zb6OVofvC37kOjp0/Wk7G7zOpOj0vMHxi/3FQafXP3UIon7so6lM+ALQOflDpEmGyk2qvz2QFLMZxdbSatwsQ1vz6A2i/OyfUhb9dxw==" }"

Note:

The lifetime of the authentication token for a user is one day. To get a new authentication token, you need to authenticate yourself again.

Authorization

You can access the knowledge information from the repository only with proper authorization. To get authorization, you need to acquire an authentication token as shown in the following example or use OAuth 2.0 framework if you are a staff account or a contact user. For more information on OAuth, see Authenticating and Authorizing the Staff Account or the Contact User using OAuth 2.0 section in Authenticate and Authorize.

If you chose to use Basic Authentication, you must acquire an authentication token and then include it in the kmauthtoken token as integrationUserToken as shown in the following example. Also, specify your authorization credentials and user external type in the command as shown in the example. Then, run the cURL command to get authorization as a console user or web user.

curl -X POST  https:// sitename.example.com/km/api/latest/auth/authorize -H 'Accept: application/json' -H 'Content-Type: application/x-www-form-urlencoded' -H 'kmauthtoken: {"siteName":" example_site ","integrationUserToken":"+lOR60Szzpk+3aiBn2uJ3BSqBrT79DaIVoC8zb6OVofvC37kOjp0/Wk7G7zOpOj0vMHxi/3FQafXP3UIon7so6lM+ALQOflDpEmGyk2qvz2QFLMZxdbSatwsQ1vz6A2i/OyfUhb9dxw=="}' -d 'userName=user_name&password=passWorD&siteName= example_site &userExternalType=ACCOUNT'

Typically, a kmauthtoken contains the following parameters:

integrationUserToken: Describes the token generated after authenticating a user.
siteName: Describes the name of the site.
userToken: Describes the token generated after authenticating ACCOUNT or CONTACT type user.
interfaceId: Describes the interface identifier if user is using Oracle B2C Service.
requiresBillable: True if the request should track billable session.
captureAnalytics: True if the request should capture analytics.
localeId: Describes the language and the country it represents.
localeOverride: If true, then localeId is used. If false, then Accept-Language header is used. Default is false.
appId: Describes the application ID.
knowledgeInteractionId: Describes the ID that will be used as the sessionId for the request.
interactionIdGenerated: True if the interaction ID is generated.
referrer: Describes the referrer for the request.
querySource: Describes the source of query.
clientIP: Describes the client IP passed by CP.

Note:

If you are a web user, specify CONTACT as the userExternalType value in the preceding command.

After authorization is successful, a response similar to the following is returned.

{
   "authenticationToken" : "{"localeId":"en_US","knowledgeInteractionId":null,"appId":null,"siteName":"im_rest_api_site","interfaceId":null,"requiresBillable":null,"captureAnalytics":null,"integrationUserToken":null,"userToken":"+lYnC/ZZ5wnEokM5P0uQrOuRm4934SYSbyE/BjmDj22Fou/nCPAAcWKpPrAn6kPC6rW0sfhIyT6vG97jH6OKd8CWljNXGJEgUWprqoS8cy5Iy28Qzkeg+Z9kCpmYvovtbzMoGsQ4jusnKAVn/it6Ag==","referrer":null,"querySource":null,"clientIP":null,"localeOverride":null}",
   "user" : {
      "defaultLocale" : {
         "recordId" : "en_US"
      },
	  "isLocked" : false,
      ...
      "dateModified" : "2018-06-28T09:45:32-0600"
   }
}

Your authorization and authentication information gets passed in the Authorization key of the request header. When passing JWT tokens in Postman, the Authorization key must include Bearer, followed by the token. For more information, see Use JSON Web Token for Authorization.

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, find a list of IncidentLink objects for all the incidents linked to the specified Content object. You can do this using the describe action in cURL:

curl -X GET https://site.example.com/km/api/latest/content/{id}/incidentLinks -H "Accept: application/json" -H "Content-Type: application/json" -H "kmauthtoken: {"siteName":"example_site","integrationUserToken":"+lOR60Szzpk+3aiBn2uJ3BSqBrT79DaIVoC8zb6OVofvC37kOjp0/Wk7G7zOpOj0vMHxi/3FQafXP3UIon7so6lM+ALQOflDpEmGyk2qvz2QFLMZxdbSatwsQ1vz6A2i/OyfUhb9dxw=="}" -d "userName=user_name&password=passWorD&siteName=example_site&userExternalType=ACCOUNT"

This is how the request looks in Postman:

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

If your request for information about the Content 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 clients, review the failure Status Codes, and then try again.

{
  "isForEdit" : true,
  "replacementTokens" : [ {
    "dateModified" : "284852364-01-15T07:07:46EST",
    "replacementText" : "REPLACEMENTTEXT_VALUE",
    "replacementTextNonFormatted" : "REPLACEMENTTEXTNONFORMATTED_VALUE",
    "tokenType" : "TOKENTYPE_VALUE",
    "tokenName" : "TOKENNAME_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "https://site.example.com/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "https://site.example.com/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  } ],
  
  ...
  
  "versionId" : "VERSIONID_VALUE",
  "documentId" : "DOCUMENTID_VALUE",
  "title" : "TITLE_VALUE",
  "version" : "VERSION_VALUE",
  "answerId" : 1428416791848,
  ...
  "owner" : {
   ...
  },
  "wfStepNotificationOverride" : "2013-04-23T21:06:26EDT",
  "xml" : "XML_VALUE",
  "metaDataXml" : "METADATAXML_VALUE",
  "resourcePath" : "https://site.example.com/okcs/resources/{TENANTID}/content/draft/{CONTENTID}/{CONTENTTEXTID}/{FILENAME_WITH_EXTENSION}?login={USER_NAME}",
  "metaDataResourcePath" : "METADATARESOURCEPATH_VALUE"
}

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 in Postman.

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

Explore the Learn More section to better manage collections.
Join the Oracle Developer Community, where you can share tips and advice with others.