Work with the Capping API work

The Capping API helps you create, configure and monitor your capping configurations.

This section provides global information on how to work with the API. A detailed API description is available in Adobe Journey Optimizer APIs documentation.

Capping API description

Method
Path
Description
POST
list/endpointConfigs
Get a list of the endpoint capping configurations
POST
/endpointConfigs
Create an endpoint capping configuration
POST
/endpointConfigs/{uid}/deploy
Deploy an endpoint capping configuration
POST
/endpointConfigs/{uid}/undeploy
Undeploy an endpoint capping configuration
POST
/endpointConfigs/{uid}/canDeploy
Check if an endpoint capping configuration can be deployed or not
PUT
/endpointConfigs/{uid}
Update an endpoint capping configuration
GET
/endpointConfigs/{uid}
Retrieve an endpoint capping configuration
DELETE
/endpointConfigs/{uid}
Delete an enpoint capping configuration

When a configuration is created or updated, a check is automatically performed to guarantee the syntax and the integrity of the payload.
If some problems occur, the operation returns warning or errors to help you correct the configuration.

Endpoint configuration

Here is the basic structure of an endpoint configuration:

{
    "url": "<endpoint URL>",  //wildcards are allowed in the endpoint URL
    "methods": [ "<HTTP method such as GET, POST, >, ...],
    "services": {
        "<service name>": { . //must be "action" or "dataSource"
            "maxHttpConnections": <max connections count to the endpoint (optional)>
            "rating": {
                "maxCallsCount": <max calls to be performed in the period defined by period/timeUnit>,
                "periodInMs": <integer value greater than 0>
            }
        },
        ...
    }
}
IMPORTANT
The maxHttpConnections parameter is optional. It allows you to restrict the number of connections Journey Optimizer will open to the external system.
The max value that can be set is 400. If nothing is specified, then the system may open up to multiple thousands of connections depending on the dynamic scaling of the system.
When the capping configuration is deployed, if no ‘maxHttpConnection’ value has been provided, a default “maxHttpConnection = -1” is added into the deployed configuration, meaning that Journey Optimizer will use the default system value.

Example:

`{
  "url": "https://api.example.org/data/2.5/*",
  "methods": [
    "GET"
  ],
  "services": {
    "dataSource": {
      "rating": {
        "maxCallsCount": 500,
        "periodInMs": 1000
      }
    }
  }
}

Warning and errors

When a canDeploy method is called, the process validates the configuration and returns the validation status identified by its Unique ID, either:


"ok" or "error"

The potential errors are:

  • ERR_ENDPOINTCONFIG_100: capping config: missing or invalid url
  • ERR_ENDPOINTCONFIG_101: capping config: malformed url
  • ERR_ENDPOINTCONFIG_102: capping config: malformed url: wildchar in url not allowed in host:port
  • ERR_ENDPOINTCONFIG_103: capping config: missing HTTP methods
  • ERR_ENDPOINTCONFIG_104: capping config: no call rating defined
  • ERR_ENDPOINTCONFIG_107: capping config: invalid max calls count (maxCallsCount)
  • ERR_ENDPOINTCONFIG_108: capping config: invalid max calls count (periodInMs)
  • ERR_ENDPOINTCONFIG_111: capping config: can’t create endpoint config: invalid payload
  • ERR_ENDPOINTCONFIG_112: capping config: can’t create endpoint config: expecting a JSON payload
  • ERR_AUTHORING_ENDPOINTCONFIG_1: invalid service name <!--<given value>-->: must be ‘dataSource’ or ‘action’

The potential warning is:

ERR_ENDPOINTCONFIG_106: capping config: max HTTP connections not defined: no limitation by default

Use-cases

In this section, you will find the five main use-cases that you can perform to manage your capping configuration in Journey Optimizer.

To help you in your testing and configuration, a Postman collection is available here.

This Postman Collection has been set up to share the Postman Variable collection generated via Adobe I/O Console’s Integrations > Try it out > Download for Postman, which generates a Postman Environment file with the selected integrations values.

Once downloaded and uploaded into Postman, you need to add three variables: {JO_HOST},{BASE_PATH} and {SANDBOX_NAME}.

  • {JO_HOST} : Journey Optimizer Gateway URL
  • {BASE_PATH} : entry point for the API.
  • {SANDBOX_NAME} : the header x-sandbox-name (for example, ‘prod’) corresponding to the sandbox name where the API operations will take place. See the sandboxes overview for more information.

In the following section, you will find the Rest API calls ordered list to perform the use-case.

Use-Case n°1: Creation and deployment of a new capping configuration

  1. list
  2. create
  3. candeploy
  4. deploy

Use-Case n°2: Update and deploy a capping configuration not deployed yet

  1. list
  2. get
  3. update
  4. candeploy
  5. deploy

Use-Case n°3: Undeploy and delete a deployed capping configuration

  1. list
  2. undeploy
  3. delete

Use-Case n°4: Delete a deployed capping configuration.

In only one API call, you can undeploy and delete the configuration with the use of the forceDelete parameter.

  1. list
  2. delete, with forceDelete param

Use-Case n°5: Update a capping configuration already deployed

  1. list
  2. get
  3. update
  4. undeploy
  5. candeploy
  6. deploy
recommendation-more-help
b22c9c5d-9208-48f4-b874-1cefb8df4d76