Application API: Define event types for features

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>/eventtype

The following table describes the complete JSON payload for the call.

Request JSON
{
   "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>
}
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
that the registering endpoint publishes to UBX.

SUBSCRIBE: Identifies
an event that the registering endpoint receives from UBX.

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
initiated by a single individual who can be identified by a unique identifier. Configures the event
to include identifiers.

Aggregate: For events that are initiated by or
affect multiple individuals. Configures the event to exclude identifiers.

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.
Enter as a number only.

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.

Join The Discussion

Your email address will not be published. Required fields are marked *