1. OKCS REST APIREST API for Knowledge Advanced in B2C Service
  2. Reference
  3. Best Practices

Best Practices

If you have already built a custom application using the REST APIs for Knowledge Advanced in B2C Service, you can use this topic to optimize your implementation. If you are just starting an implementation, you can use the best practices described here to build your application in the most efficient way:

Performance Optimization

You can optimize the performance of your application by making sure that you are using the REST services in an efficient manner. You can locally log all your REST calls and review the log files to find out if you are making any unnecessary repetitive calls.

Here are some common REST scenarios that can adversely affect application performance:

  • Repeat calls: Repeatedly retrieving data, which has been already retrieved, and is likely still valid.
  • Large list requests: Retrieving a large number of objects, when you actually need a small subset of the objects for your use case.
  • Large object requests: Retrieving a mode of object, which is larger than what your use case requires.

Repeat calls

  • Repeated Authentication:
    • Integration 
      POST /km/api/latest/auth/integration/authorize
    • User 
       POST /km/api/v1/auth/authorize

    For more information, see Authentication and Caching.

  • Repeated calls for commonly cacheable data types:

    Here are some examples of inefficient calls. Reviewing your logs and finding repeated API calls can help you locate the inefficiencies in your implementation.

    • ContentTypes (Getting list multiple times): 
      GET /km/api/v1/contentTypes?orderBy=referenceKey
    • ContentTypes (Getting single ContentType multiple times): 
      GET /km/api/v1/contentTypes/<channelName>?mode=FULL
    • Repository Locales: 
      GET /km/api/v1/repositories/default/availableLocales?mode=full
    • User Subscriptions: 
      GET /km/api/v1/users/<guid>/subscriptions?mode=FULL

    For more information, see Caching.

Large List Requests

  • Setting high limits: 
    GET /km/api/latest/content?q=dateModified%20after%20'2018-09-18'%20and%20contentType.refKey%20eq%20'<channelName>'&offset=0&limit=1000

    For more information, see Limits in Restricting Data.

Large Object Requests

Mode size inefficiency can lower the performance of your application. Here's an example of an inefficient call. Review your use case and the available modes (Full, Extended, Data, and Key) to determine what is appropriate.

  • Full Mode 
    GET /km/api/latest/content?q=filterMode.contentState+eq+'LATESTVALID'&mode=FULL&contentType.refKey=ANSWER&limit=100&offset=0

    For more information, see Modes in Restricting Data.

Authentication

Here are some authentication token REST API call issues.

Integration User Token

Item Description
REST Action/URL 
POST /km/api/latest/auth/integration/authorize
Validity 24 hours
Typical Misuse Significant number of repeat calls within reasonably cacheable period.
Background

This token determines which REST API calls the users of a given Integration type have access to. As the Integration User Token is valid for 24 hours, you do not need to obtain a new token repeatedly until it expires. Additionally, if a given integration type (i.e. contact users) is making the same type of calls, this Integration User Token can be shared between the users. You do not need to make this call for each user logging in.

This is considered a caching issue. For more information, see Advanced Cache Management.

Suggestion Cache the Integration Token in the Application level cache Implement method to obtain a new token upon expiration.

User Token

Item Description
REST Action/URL 
POST /km/api/v1/auth/authorize
Validity 24 hours
Typical Misuse Significant number of repeat calls within reasonably cacheable period.
Background As the User Token is valid for 24 hours, you do not need to obtain a new token repeatedly for the same user.
Suggestion Cache the User Token in the Session level cache Implement method to obtain new token upon expiration.
For more information, see Authenticate and Authorize.

Caching

If you have previously requested data that is considered valid, and if you need the data again during the same session, then you should not request the data again until the validity period has expired. This tenet applies to all the available data objects fetched by using Oracle B2C Service Knowledge Advanced REST services. The endpoints mentioned below (contentTypes, repositories, users, etc.) are intended as examples, which you should look for, for any repeat patterns in your calls.

Requesting a List Repeatedly

Item Description
REST Action/URL

Content Types

GET /km/api/v1/contentTypes?orderBy=referenceKey

Repository Locales

GET /km/api/v1/repositories/default/availableLocales?mode=full

User Subscriptions

GET /km/api/v1/users/<guid>/subscriptions?mode=FULL
Typical Misuse Significant number of repeat calls within reasonably cacheable period.
Background

In the Content Type example, the client is requesting an unbounded list of all of the Content Types. For most customers/use cases, Content Types rarely change within the scope of a session, let alone for days, weeks or even months in many cases.

In the Repository Locale example, the client is requesting an unbounded list of all of available Locales for the Repository. For most customers/use cases, Locales assigned to a repository rarely change within the scope of a session, let alone for days, weeks or even months in many cases.

In the User Subscription example, the client is requesting Subscriptions for the User. For most customers/use cases, Subscriptions for a User rarely change within the scope of a session.
Suggestion

For the Content Type example, cache the returned list in the Session level cache (appropriate as the list returned is based on the authorization of the current user).

For the Repository Locales example, cache the returned list in the Application level cache (appropriate as the list returned is based on the configuration of the system).

For the User Subscription example, cache the returned list in the Session level cache.
Exceptions Note that if you are actively using the Oracle B2C Service Knowledge Advanced REST APIs to create, edit or delete records, you will need to update your cache appropriately. For more information, see Advanced Cache Management.

Requesting an Single Identifiable Record Repeatedly

Item Description
REST Action/URL 
GET /km/api/v1/contentTypes/<channelName>?mode=FULL
Typical Misuse Significant number of repeat calls within reasonably cacheable period
Background In this example, the client is requesting the details of a single Content Type. For most customers/use cases, Content Types rarely change within the scope of a session, let alone for days, weeks or even months in many cases.
Suggestion

Cache the item in the Application or Session level cache.

If you have previously loaded a List of Full Content Type objects, you could pull the required values directly from the cache, instead of making another call.
Exceptions If you are actively using Oracle B2C Service Knowledge Advanced REST APIs to create, edit or delete records, you will need to update your cache appropriately. For more information, see Advanced Cache Management.

Advanced Cache Management

Here are a few tips to keep your cache in sync.

Managing Cache Creates/Updates/Deletes

Item Description
Create If you are maintaining a cached list of data for a given type, add the new object to the list cache after successful submission of the new object to the REST service. This avoids pulling down a complete new list just to get the new object.
Update If you are maintaining a list or an individual data object within your client cache, be sure to update it within your cache after successful submission of the updated object to the REST service.
Delete After successfully deleting an object from the REST service, be sure to delete any client cached instances of the object.

Managing Cache Read (New/Changed)

Item Description
Read

If you have previously requested and cached a list, but have use cases that may include data changing during the scope of your session, consider using a combination of the information you know about your cached data and a Q-Query to find new/updated data.

For instance, by keeping track of the last time you did a full read of the content, you could formulate a Q-Query with a clause containing:

dateAdded gt '2011-11-01T06:00:00' or dateModified gt '2011-11-01T06:00:00'

You would then add the returned data to your local cache.

Restricting Data

You can minimize the amount of data to be retrieved by fetching only what is required. This can be achieved in the following ways:

  • Limits - Limiting result set size
  • Modes - Limiting the size of data objects
  • Q-Queries - Applying filter clause to narrow result set
  • XML vs JSON

Limits

Item Description
When to use When you have REST API calls that do not use limit or offset.
Suggestion Most use cases do not require retrieving entire tables of data. Instead, you can retrieve the data in smaller chunks 'pages', and you can make subsequent REST API calls to retrieve additional pages if and when necessary.

For more information, see Manage Collections.

Modes

Item Description
When to use You must set the appropriate mode for your use case.
Suggestion In many use cases, for instance, a list of news items on a landing page, there is a need only for a document title to be displayed (and behind the scenes, a unique key identifier RecordID for acting on the item). In such case, you do not need to request the fully loaded object for the minor subset of data that you require.
Example URLs

/km/users?mode=key // should return a list of UserKeyBO objects

/km/users?mode=data // should return a list of UserDataBO objects

/km/users?mode=full // should return a list of UserBO objects

When building your applications, you must request the lightest weight object that fulfills the need.

Data Suggested Mode Detail
Lists Key Most lists only require a title and a unique identifier, which the key provides.
Detail
  • Data
  • Extended
  • Full
 Depending on your use case, you can utilize one of the modes. Try to use the smallest mode possible.

Note:

If the mode is not specified, the default mode defined for the service is returned. However, this may be a mode that is larger than necessary. You need to ensure that your REST API calls include the appropriate mode.

Q-Queries

Item Description
When to use In many cases, you should use Q-Queries when you do not to request the complete list of a data object. For instance, you need to analyze whether you need all the content, or will the content from within the last 7 days be sufficient.
Suggestion A Q-Query to limit the scope of the results with the appropriate paging and modes is the key to keeping your results targeted, while efficiently utilizing Client, Server and Network resources.

For more information, see Supported Query Parameters.

XML vs JSON

Your application has the option of using JSON or XML for your payloads. As JSON does not have the same overhead (opening and closing tags) as XML, consider using JSON where possible. Using JSON reduces the data sent over the network, and it is also a native format for JavaScript clients, which results in lesser client-side cycles required to parse the response.

API Limits and Defaults

You need to be aware of the following API limits and defaults when working with the Oracle B2C Service Knowledge Advanced REST APIs.

Item Limitation Default
Batch Size 1000 20
Default Mode   Depends on object type