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 .
Capping API description & Postman collection description
The table below lists the available commands for the capping API. Detailed information including request samples, parameters, and response formats is available in the .
{uid}
/deploy{uid}
/undeploy{uid}
/canDeploy{uid}
{uid}
{uid}
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.
In addition, a Postman collection is available to help you in your testing configuration.
This collection has been set up to share the Postman Variable collection generated via > 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, 鈥榩rod鈥) corresponding to the sandbox name where the API operations will take place. See the sandboxes overview for more information.
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>
}
},
...
}
}
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鈥檛 create endpoint config: invalid payload
- ERR_ENDPOINTCONFIG_112: capping config: can鈥檛 create endpoint config: expecting a JSON payload
- ERR_AUTHORING_ENDPOINTCONFIG_1: invalid service name
<!--<given value>-->
: must be 鈥榙ataSource鈥 or 鈥榓ction鈥
The potential warning is:
ERR_ENDPOINTCONFIG_106: capping config: max HTTP connections not defined: no limitation by default
Use cases
This section lists key use cases for managing capping configurations in Journey Optimizer and the associated API commands required to implement the use case.
Details on each API command is available in the API description & Postman collection.
API calls to use:
list
鈥 Retrieves existing configurations.create
鈥 Creates a new configuration.candeploy
鈥 Checks whether the configuration can be deployed.deploy
鈥 Deploys the configuration.
API calls to use:
list
鈥 Retrieves existing configurations.get
鈥 Fetches details of a specific configuration.update
鈥 Modifies the configuration.candeploy
鈥 Checks deployment eligibility.deploy
鈥 Deploys the configuration.
API calls to use:
list
鈥 Retrieves existing configurations.undeploy
鈥 Undeploys the configuration.delete
鈥 Removes the configuration.
In only one API call, you can undeploy and delete the configuration with the use of the forceDelete
parameter.
API calls to use:
list
鈥 Retrieves existing configurations.delete
(withforceDelete
parameter) 鈥 Forces deletion of a deployed configuration in a single step.
note note |
---|
NOTE |
A redeployment is required after updating an already deployed configuration. |
API calls to use:
list
鈥 Retrieves existing configurations.get
鈥 Fetches details of a specific configuration.update
鈥 Modifies the configuration.undeploy
鈥 Undeploys the configuration before applying changes.candeploy
鈥 Checks deployment eligibility.deploy
鈥 Deploys the updated configuration.