Call UBX application APIs to define event types for features that you add to UBX applications.
POST /v1/application/{applicationID}/feature/{featureID}/eventtype
Add an event type to a feature that is part of a UBX application.
About this API
Use this API to define events that are available to a UBX endpoint that is based on a UBX application. The event type must be a UBX recognized event or an IBM approved custom event. You define an event type by specifying a recognized event code that appears in the UBX Dynamic Event Library, various required and best practice attributes from the Library, and other information to describe the event type.
Event types are made available to UBX endpoints by associating them with features that you add to UBX applications. An application can contain multiple different features and each feature can contain multiple different event types. You can also define the same event type for different features, but an event type must be defined the same way in each feature for the same application.
Before you begin
Create or select the feature to which you want to add event types. You must know the unique external featureID for the feature and the unique applicationID that identifies the application.
Request
You must specify the account-level authentication key that IBM provided for your UBX account.
The base URL is the URL that IBM assigned to your account during the initial account provisioning process.
The application ID is the value that UBX generated when you created the application with the call to POST v1/application. The featureID is the system-generated value that was defined by calling POST v1/application/<applicationID>/feature.
In the attributes section, provide values that describe the event. Provide the names of the attributes that the event provides, and indicate the type of data that each attribute delivers. The UBX user interface uses the values that you provide to describe the event.
Enter as many attribute descriptions as your business systems can provide for the event.
The following example illustrates a request (using curl) to create a feature and associate it with a UBX application:
curl -v
-X POST
-H "Authorization: Bearer <application-level authentication key>"
-H "Content-Type: application/json"
-d ’{“code” : “<recognized event code>”,"name":"<recognized event name>",
"registrationType":"<registration type>","attributes":[{"name":"<attribute name>",
"type":"<attribute type>"}],"scope":"aggregate|individual",
"description":"<event description>"},"namespace":"<event namespace>",
"version":"<event library version>"
https://<base URL>/v1/application/<applicationID>/feature/<featureID>/eventtypeThe following table describes the complete JSON payload for the call.
| Request JSON |
|---|
|
| Property | Use | Data type | Valid value | Description |
|---|---|---|---|---|
| code | Required | String | As provided by IBM | A value that IBM provides to uniquely identify the event. Example: ibmcartPurchase. |
| name | Required | String | As defined in the endpoint application | The value that you enter here becomes the event display name in the UBX user interface. Example: orderTotal. |
| registrationType | Optional | String | PUBLISH
SUBSCRIBE |
Default: PUBLISH
PUBLISH: Identifies an event SUBSCRIBE: Identifies |
| name | Required | String | As registered with UBX | Name of the attribute. Example: orderTotal. |
| type | Required | String |
String Number Boolean Time in ISO-8601 format |
The type of data that is provided by the event. Example: number |
| scope | Required | String |
Aggregate Individual |
Default: Individual
Individual: For events Aggregate: For events that are initiated by or |
| namespace | Optional | String | As defined in the endpoint application | Default: "com.ibm.commerce.ubx"
Enter a different namespace if you define a custom event with a code that duplicates an event code that is already registered with UBX. |
| version | Optional | Number | As defined in the endpoint application | Default: 1
Specify the version of the UBX Dynamic Event ibrary. |
Response
UBX public APIs return standard HTTP 1.1 response codes.
A successful call response includes a JSON payload that matches the payload of the request.
PUT /v1/application/{applicationid}/feature/{featureid}/eventtype/{code}
Update an event type that is defined for a feature that is part of a UBX application.
About this API
Call this API to update event types that will be available to UBX endpoints through the definition of UBX applications and features. As you implement and maintain your business solution with UBX, you can call this API to make necessary adjustments and additions.
Request
You must specify the account-level authentication key that IBM provided for your UBX account.
The application ID is the value that UBX generated when you created the application with the call to POST v1/application. The featureID is the system-generated value that was defined by calling POST v1/application/<applicationID>/feature.
The request must specify a single event type code to identify the event type that you want to update.
The structure of the JSON payload for the PUT call is identical to the payload structure for the POST call, except that the value for code is optional in the request body. If you put the code in the request JSON, UBX compares it to the value that is specified as a URL
parameter in the request. The API reports an error if it detects an inconsistency between the code values. Update any other the values that you want to change.
The following example illustrates a request (using curl) to update an application that publishes events:
curl -v
-X PUT
-H "Authorization: Bearer <application-level authentication key>"
-H "Content-Type: application/json"
-d ’{"name":"<recognized event name>","registrationType":"<registration type>",
"attributes":[{"name":"<attribute name>","type":"<attribute type>"}],
"scope":"aggregate|individual","description" : "<event description>" },
"namespace":"<event namespace>","version":<event catalog version>
https://<base URL>/v1/application/<applicationID>/feature/<featureID>/
eventtype/<code>Response
UBX public APIs return standard HTTP 1.1 response codes.
A successful call response includes a JSON payload that contains the updated values. The updated event type definition must contain attributes that are marked as required attributes in the UBX Event Catalog. The value for code cannot change.
GET /v1/application/{applicationid}/feature/{featureID}eventtype/{code}
Request information about an event type that is defined for a feature that is part of a UBX application.
About this API
Call this API to retrieve information about the event types that have been added to features that are added to a UBX application. The event types that are added to the feature are the event types that are available to UBX users through the UBX endpoint that is based on the UBX application.
Request
You must specify the account-level authentication key that IBM provided for your UBX account.
The application ID is the value that UBX generated when you created the application with the call to POST v1/application. The featureID is the external feature ID that you defined when you generated the
feature by calling POST v1/application/<applicationID>/feature.
The code is the recognized event code that you specified when you added the event type to the feature by calling POST v1/application/<applicationID>/feature/<featureID>/eventtype. The event code must be the code that is defined for the recognized event in the UBX Event Catalog. For custom events, the code must be the approved event code that was submitted to IBM.
The base URL is the URL that IBM assigned to your account during the initial account provisioning process. Make the call with an empty request body.
The following example illustrates a request (using curl) to retrieve details for a feature that was created for the specified application:
curl -v
-X GET
-H "Authorization: Bearer <account-level authentication key>"
-H "Content-Type: application/json"
https://<base URL>/v1/application/<applicationID>/feature/<featureID>/
eventtype/<code>Response
UBX public APIs return standard HTTP 1.1 response codes.
A successful response includes a JSON payload that describes the specified event type. The JSON matches the payload that was used in the call to POST v1/application/<applicationID>/feature/<featureID>/eventtype to add the event type to the feature.
DELETE /v1/application/{applicationid}/feature/{featureid}/eventtype/{code}
Remove an event type that is defined for a feature that is part of a UBX application.
About this API
Call this API to remove an event type from the feature that is specified by the featureID that you include in the request URL.
Request
You must specify the account-level authentication key that IBM provided for your UBX account.
The application ID is the value that UBX generated when you created the application with the call to POST v1/application. The featureID is the external feature ID that you defined when you generated the feature by calling POST v1/application/<applicationID>/feature.
The code is the recognized event code that you specified when you added the event type to the feature by calling POST v1/application/<applicationID>/feature/<featureID>/eventtype. The event code must be the code that is defined for the recognized event in the UBX Event Catalog. For custom events, the code must be the approved event code that was submitted to IBM.
The base URL is the URL that IBM assigned to your account during the initial account provisioning process. Make the call with an empty request body.
The following example illustrates a request (using curl) to remove the specified UBX application:
curl -v
-X DELETE
-H "Authorization: Bearer <account-level authentication key>"
-H "Content-Type: application/json"
https://<base URL>/v1/application/<applicationID>/feature/<featureID>/
eventtype/<code>Response
UBX public APIs return standard HTTP 1.1 response codes.