Application APIs/ Define application deployments

Acoustic Exchange provides APIs that you can call to define your application deployments to various data centers.

POST /v1/application/{applicationID}/deployment

Define a Acoustic Exchange application deployment.

About this API

Call this API to provide Acoustic Exchange with the access information it requires to communicate with your endpoint. Exchange endpoints are based on Acoustic Exchange applications that support connecting to multiple data centers. For example, Acoustic Exchange deployments allow you to distribute user traffic across endpoints deployed on multiple data centers based on organization assignments.

Before you begin

Create or select the application that you will associate with the deployment. 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 ’{"deploymentId":"<deployment ID>","displayName":"<deployment name>",
"description":"<deployment description>","eventDestinationUrl":
"<event subscriber URL>",  "audienceSourceUrl":"<audience provider URL>",
"audienceDestinationUrl":"<audience consumer URL>" },
https://<base URL>/v1/application/<applicationID>/deployment

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

Request JSON

{
   "deploymentId":"<deployment ID>",
   "displayName":"<deployment name>",
   "description":"<deployment description>",
   "eventDestinationUrl":"<event subscriber URL>",
   "audienceSourceUrl":"<audience provider URL>",
   "audienceDestinationUrl":"<audience consumer URL>"
}

Property	Use	Data type	Valid value	Description
deploymentId		string	User defined	Brief identifier to distinguish the deployment from others that are defined within a Acoustic Exchange application. Each deploymentID must be unique within the application that is defined by the specified applicationID.
displayName			User defined	Unique name to distinguish the deployment from others that are defined within a Acoustic Exchange application.
description		String	User defined	Brief description of the deployment.
event DestinationUrl	Optional	URL	URL	The URL that receives event data from Acoustic Exchange. Can be null if the endpoint does not exchange event data.
audience SourceUrl	Optional	URL	URL	The URL from which the endpoint uploads audience data to Acoustic Exchange. Can be null if the endpoint does not exchange audience data as an audience provider.
audience DestinationUrl	Optional	URL	URL	The URL from which the endpoint uploads audience data to Acoustic Exchange. Can be null if the endpoint does not exchange audience data as an audience provider.

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}/deployment/{deploymentid}

Update the deployment definition for an Acoustic Exchange application.

About this API

Call this API to change the information that Acoustic Exchange uses to connect to your endpoint on various data centers.

Request

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

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

The request must specify a single deploymentID to identify the deployment that you want to update. The deploymentID is the value that you defined when you generated the feature by calling POST v1/application//deployment.

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 deploymentID is optional in the request body. If you put the deployment ID 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 ID values. Update any other the values that you want to change.

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.

GET /v1/application/{applicationid}/deployment/{deploymentid}

Request information about a specific deployment definition.

About this API

Acoustic Exchange endpoints are based on Exchange applications that support connecting to multiple data centers. Call this API to request details about a deployment that provides Acoustic Exchange with the access information it requires to communicate with the data centers. The API returns an application deployment object that lists the details in JSON format.

Request

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

The application ID is the value that 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 retrieve details for a feature that was created for the specified application:

curl -v 
-X GET 
-H "Authorization: Bearer <application-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>/deployment/<deploymentID>?extraFields=true

Query parameter	Value	Description
extraFields	true\|false	By including the extraFields query parameter in the RL, the call returns additional information about the deployment.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

A successful response includes a JSON payload that describes the specified deployment. The JSON matches the payload that was used in the call to POST v1/application//deployment to define the application deployment.

Example response (values are presented for example only):

[
  {
    "deploymentId": "<ID>",
    "displayName": "<Name",
    "description": "<Text>",
    "eventDestinationUrl": "<Event URL>",
    "audienceSourceUrl": "<Source URL>",
    "audienceDestinationUrl": "<Destination URL>",
    "location": "<Text>",
    "deprecated": false
  }
]

JSON	Output
deploymentId	Brief identifier to distinguish the deployment from others that are defined within an Exchange application. Each deploymentID must be unique within the application that is defined by the specified applicationID.
displayName	Unique name to distinguish the deployment from others that are defined within an Exchange application.
description	Brief description of the deployment.
eventDestinationUrl	The URL that receives event data from Exchange. Can be null if the endpoint does not exchange event data.
audienceSourceUrl	The URL from which the endpoint uploads audience data to Exchange. Can be null if the endpoint does not exchange audience data as an audience provider.
audienceDestinationUrl	The URL that receives audience data from Exchange. Can be null if the endpoint does not receive audience data.
location	The location of the deployment.
deprecated	If the deployment is deprecated, this field returns true. If the deployment is not deprecated, this field returns false.

GET /v1/application/{applicationid}/deployment/all

Request information about all of the deployments that have been defined for a Acoustic Exchange application.

About this API

Acoustic Exchange endpoints are based on Exchange applications that support connecting to multiple data centers. Call this API to request access information for all of the data centers that Exchange must access to support the Acoustic Exchange endpoints that are based on the specified application. This API returns an array of application deployment objects that list the details in JSON format.

Request

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

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

This API request does not specify a single deploymentID. Instead, you make this call without specifying a specific deployment so that the call returns information for every deployment that is defined for the specified 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 retrieve details for a feature that was created for the specified application:

curl -v 
-X GET 
-H "Authorization: Bearer <application-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>/deployment?extraFields=true

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

A successful response includes an array of application deployment objects, each of which lists details about a deployment in JSON format. The JSON matches the payload that was used in the call to POST v1/application//deployment to define the application
deployment.

Example response (values are presented for example only):

[
  {
    "deploymentId": "<ID>",
    "displayName": "<Name",
    "description": "<Text>",
    "eventDestinationUrl": "<Event URL>",
    "audienceSourceUrl": "<Source URL>",
    "audienceDestinationUrl": "<Destination URL>",
    "location": "<Text>",
    "deprecated": false
  }
]

JSON	Output
deploymentID	Brief identifier to distinguish the deployment from others that are defined within an Exchange application. Each deploymentID must be unique within the application that is defined by the specified applicationID.
displayName	Unique name to distinguish the deployment from others that are defined within an Exchange application.
description	Brief description of the deployment.
eventDestinationUrl	The URL that receives event data from Exchange. Can be null if the endpoint does not exchange event data.
audienceSourceUrl	The URL from which the endpoint uploads audience data to Exchange. Can be null if the endpoint does not exchange audience data as an audience provider.
audienceDestinationUrl	The URL that receives audience data from Exchange. Can be null if the endpoint does not receive audience data.
location	The location of the deployment.
deprecated	If the deployment is deprecated, this field returns true. If the deployment is not deprecated, this field returns false.

DELETE /v1/application/{applicationId}/deployment/{deploymentId}

Remove a specified Acoustic Exchange deployment.

About this API

Call this API to delete an existing deployment.
Note: Confirm that the deployment is not specified by other applications.
###Request
You must specify the account-level authentication key that Acoustic provided for your Exchange account.

The application ID is the value that Exchange generated when you created the application with the call to POST v1/application. The deploymentID is the deployment that you defined when you generated the feature by calling POST v1/application//deployment.

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 connection information:

curl -v 
-X DELETE 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/{applicationid}/deployment/
{deploymentid}

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

A successful call removes the deployment that you specified in the request.