Application API/ Define event types for features

Call Acoustic Exchange application APIs to define event types for features that you add to Acoustic Exchange applications.

POST /v1/application/{applicationID}/feature/{featureID}/eventtype

Add an event type to a feature that is part of an Acoustic Exchange application.

About this API

Use this API to define events that are available to a Acoustic Exchange endpoint that is based on an Acoustic Exchange application. The event type must be an Acoustic Exchange recognized event or an Acoustic Exchange approved custom event. You define an event type by specifying a recognized event code that appears in the Acoustic Exchange 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 Acoustic Exchange endpoints by associating them with features that you add to Acoustic Exchange 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 Acoustic provided for your Acoustic Exchange account.

The base URL is the URL that Acoustic Exchange assigned to your account during the initial account provisioning process.

The application ID is the value that Acoustic Exchange 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//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 Acoustic Exchange 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 an Acoustic Exchange 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 Acoustic	A value that Acoustic Exchange 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 Acoustic Exchange user interface. Example: orderTotal.
registrationType	Optional	String	PUBLISH SUBSCRIBE	Default: PUBLISH PUBLISH: Identifies an event that the registering endpoint publishes to Acoustic Exchange. SUBSCRIBE: Identifies an event that the registering endpoint receives from Acoustic Exchange.
name	Required	String	As registered with Acoustic Exchange	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	Enter a different namespace if you define a custom event with a code that duplicates an event code that is already registered with Acoustic Exchange.
version	Optional	Number	As defined in the endpoint application	Default: 1 Specify the version of the Acoustic Exchange Dynamic Event library. Enter as a number only.

Response

Acoustic Exchange 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 an Acoustic Exchange application.

About this API

Call this API to update event types that will be available to Acoustic Exchange endpoints through the definition of Acoustic Exchange applications and features. As you implement and maintain your business solution with Acoustic Exchange, you can call this API to make necessary adjustments and additions.

Request

You must specify the account-level authentication key that Acoustic Exchange provided for your Acoustic Exchange account.

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, Acoustic Exchange 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

Acoustic Exchange 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 Acoustic Exchange 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 an Acoustic Exchange application.

About this API

Call this API to retrieve information about the event types that have been added to features that are added to an Acoustic Exchange application. The event types that are added to the feature are the event types that are available to Acoustic Exchange users through the Acoustic Exchange endpoint that is based on the Acoustic Exchange application.

Request

You must specify the account-level authentication key that Acoustic Exchange provided for your Acoustic Exchange account.

The application ID is the value that Acoustic Exchange 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//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//feature//eventtype. The event code must be the code that is defined for the recognized event in the Acoustic Exchange Event Catalog. For custom events, the code must be the approved event code that was submitted to Acoustic.

The base URL is the URL that Acoustic Exchange 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

Acoustic Exchange 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//feature//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 an Acoustic Exchange 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 Acoustic Exchange provided for your Acoustic Exchange account.

The base URL is the URL that Acoustic Exchange 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 Acoustic Exchange 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

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.