API Throttling

API throttling is a configurable framework solution for monitoring and regulating the use of finite system resources by Oracle B2C Service applications. In Connect Common Object Model (CCOM) v1.4, API throttling has been implemented only for database connections that are assigned to inbound public API (PAPI) requests.

Using API throttling you can regulate the number of database connections assigned to an inbound PAPI request.

This topic contains the following sections:

Benefits of API Throttling

The benefits of API throttling are as follows:

Protects application pods: Pods are collections of applications or sites. API throttling prevents one or more applications from monopolizing all available database connections. It helps prevent other applications or the application pod from becoming unresponsive.
Optimal resource utilization: It improves database throughput by balancing application requests.
Proactively protects database: It reduces database downtime by preventing the database from being overloaded.
Flexible setup: The business administrator can configure the API throttling feature to suit the business needs of the organization.

Business Administrator Tasks in Oracle B2C Service

To use the API throttling framework, the business administrator must define the resource pools and applications in the Oracle B2C Service Agent Browser UI in line with the business requirements of the organization. For more information, see Regulating Inbound Public API Traffic.

Resource Pools

A resource pool is a logical collection of applications that give rise to PAPI requests. By default, there is one pool labeled Default, which can't be deleted.

In addition to the Default resource pool, the business administrator can create any number of additional resource pools. When creating a new resource pool, the administrator must, in addition to the name of the pool, specify the capacity for the pool. The capacity of the resource pool is a percentage. It indicates the fraction of concurrent database connections available to the throttling framework that you can assign to the pool. The actual number of maximum concurrent database connections that you can assign to the pool is the capacity multiplied by the number of concurrent database connections available to the throttling framework and rounded down to the nearest integer. For example, if the number of concurrent database connections available to the throttling framework is 47 and the capacity of a resource pool is 10, then the maximum number of requests for concurrent database connections for the resource pool is 4.

Note:

The business administrator can't configure the number of concurrent database connections available to the throttling framework. If you want to increase or decrease the number of database connections available to the throttling framework, submit an incident on Oracle Support.

Managed Applications

An application is a PAPI request that comes from outside the Oracle B2C Service and is tagged with a specific application code. An application code uniquely identifies the PAPI request type and is set on the header of the incoming request.

The business administrator defines the application codes for the applications and maps them to specific resource pools. If the business administrator doesn't specify the resource pool for an application code then the mapping defaults to the Default resource pool. An application code has to be unique (case insensitive) and can have a maximum of 20 characters.

Note:

The application code must be mapped to a resource pool. Otherwise, it's automatically mapped to the Default resource pool.
Applications mapped to the Default resource pool are always assigned a database connection irrespective of whether the maximum number of concurrent requests or database connections for the Default pool have been exceeded or not.

Runtime Behavior

To use API throttling for a CREST PAPI request, you must use the custom OSvC-CREST-Application-Context HTTP header to specify the application code. The application code that you specify in the request must be defined in Oracle B2C Service. The following example requests the data for the account with ID 2 having valid OSvC-CREST-Application-Context header value 'ABCD'.

Sample Request

https://mysite.example.com/services/rest/connect/latest/accounts/2

The following table lists the OSvC-CREST-Application-Context header information:

Header	Value
OSvC-CREST-Application-Context	ABCD

Assume that the number of concurrent connections available to the throttling framework is 47. The following setup indicates that a maximum of four concurrent requests or database connections are available for application code 'ABCD' that's mapped to the CREST Request Pool resource pool. Note that if additional application codes are associated with the sample CREST Request Pool below, then the four concurrent requests are shared between all the applications associated with the pool.

The following table contains the application code definition and resource pool mapping as present in Oracle B2C Service Agent Browser UI:

Application Code	Application Name	Resource Pool
ABCD	This is a sample application code for CREST.	CREST Request Pool

The following table contains the resource pool definition as present in Oracle B2C Service Agent Browser UI:

Name	Description	Capacity (Percent)	Requests
CREST Request Pool	This is a sample resource pool for CREST.	10	4

Sample Response

If the number of concurrent requests is less than or equal to four then you get a successful (status 200 OK) response that returns the account information for account ID 2.

{
  "id": 2,
  "lookupName": "George Hewitt",
  "accountHierarchy": {
...
}

If the number of concurrent requests exceeds four then you get a '503 Service Temporarily Unavailable' response. API throttling doesn't allow the request to be assigned a database connection because the resource pool limit of four was exceeded.

{
"type": "https://mysite.example.com/services/rest/connect/exceptions/OSC-CREST-00035",
"title": "Server Busy",
"status": 503,
"detail": "Resource busy, please try again later",
"instance": "https://mysite.example.com/services/rest/connect/latest/accounts/2",
"o:errorCode": "OSC-CREST-00035"
}