Application API: Define features

Call Acoustic Exchange application APIs to add features to Acoustic Exchange applications.

POST /v1/application/{applicationID}/feature

Define features for an Exchange application.

About this API

Exchange features are associated with a specific Exchange application. Event types are associated with a specific feature. In this way, features become containers for different combinations of events that can be associated with different endpoints.

The name and description that you assign as part of this API call are for internal use only. Neither appears in the Exchange user interface.

The call response includes a system-defined feature ID that you use in other application API calls.

Before you begin

Create or select the application that you will associate with the feature. You must know the unique application ID that identifies the application.

Request

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

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

The applicationID is the value that Exchange generated when you created the application with the call to POST v1/application.

The following example illustrates a request (using curl) to create a feature and associate it with an Exchange application:

curl -v 
-X POST 
-H "Authorization: Bearer <application-level authentication key>" 
-H "Content-Type: application/json" 
-d ’{“name” : “<feature name>”,"description" : "<feature description>" },

https://<base URL>/v1/application/<applicationID>/feature

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

Request JSON

{
"name" : "<feature name>",
"description" : "<feature description>"
}

Property	Use	Data type	Valid value	Description
name	Required	string	Any name	Name of the feature. Internal use only.
description	Required	string	Any description	Enter a brief description. Internal use 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 but also includes a new, system-generated property: "id" : "{external feature id}.

For example, the returned JSON includes the new external feature ID, as illustrated here.

Request JSON

{
"id" : <external feature id>
"name" : "<feature name>",
"description" : "<feature description>"
}

Acoustic Exchange uses the value of this new property to identify the feature that the API call creates. Record the value for "id" because you must specify it in other application API calls.

PUT /v1/application/{applicationID}/feature/{featureID}

Update a feature that is associated with a Acoustic Exchange application.

About this API

Call this API to make changes to the feature definition. For example, you can update the description of the feature as you make changes to the set of events that are associated with the feature.

Request

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

The applicationID 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/{applicationID}/feature.

The structure of the JSON payload for the PUT call is identical to the payload structure for the POST call. Update the values that you want to change. You cannot change the featureID.

The following example illustrates a request (using curl) to update a feature that is associated with a Acoustic Exchange application:

curl -v 
-X PUT 
-H "Authorization: Bearer <application-level authentication key>" 
-H "Content-Type: application/json" 
-d ’{"id" : <external feature id>",“name” : “<new feature name>”,
"description" : "<new feature description>" }
https://<base URL>/v1/application/<applicationID>/feature/<featureID>

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 value
for "id" does not change.

GET /v1/application/{applicationid}/feature/{externalfeatureID}

Request information about a feature that is associated with a Acoustic Exchange application.

About this API

Call this API to get details for a specific feature that is associated with a Acoustic Exchange application. The feature provides the means to associate event types with the Acoustic Exchange applications and through the application to make the event types available to Acoustic Exchange endpoints that are based on the application.

Request

You must specify the account-level authentication key that Acoustic 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 externalfeatureID is the value that you defined when you generated the feature by calling POST v1/application//feature.

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

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

A successful response includes a JSON payload that describes the specified feature.

Response JSON

{
   "applicationID":<application ID>,
   "featureID":<feature ID>,
   "externalFeatureID":"<external feature ID>",
   "name":"<feature name>",
   "description":"<description>",
   "status":<feature status>
}

Property	Data type	Valid value	Description
applicationID	string	applicationID	Identifies the application for which the feature is created. Cannot be changed.
featureID	string	feature ID	Identifies the feature. Cannot be changed.
name	string	text	Name of the feature.
description	string	text	Description of the feature.
status	integer	active = 1 inactive = 0	Indicates if the feature is active or inactive.

DELETE /v1/application/{applicationid}/feature/{featureid}

Remove a feature from a Acoustic Exchange application.

About this API

Call this API to remove 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 provided for your Acoustic Exchange account as the authorization bearer.

The application ID is the value that Acoustic Exchange generated when you created the application with the call to POST v1/application.

The base URL is the URL that Acoustic 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/<feature ID>

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.