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. Acoustic 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 IBM provided for your Acoustic Exchange account.

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

The applicationID is the value that Acoustic 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 a Acoustic 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 string 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 that receives audience data from Acoustic Exchange. Can be null if the endpoint does not receive audience data.

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 a 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 IBM 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 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/<applicationID>/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 Acoustic 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 IBM 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 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 <applicationID>/deployment.

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 <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 extraFieldsquery 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/<applicationID>/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 a Acoustic 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 a Acoustic Exchange application.
description Brief description of the deployment.
eventDestinationUrl The URL that receives event data from Acoustic Exchange. Can be null if the endpoint does not exchange event data.
audienceSourceUrl 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.
audienceDestinationUrl The URL that receives audience data from Acoustic 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 Acoustic Exchange applications that support connecting to multiple data centers. Call this API to request access information for all of the data centers that Acoustic 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 IBM 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.

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 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 <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/<applicationID>/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 a Acoustic 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 a Acoustic Exchange application.
description Brief description of the deployment.
eventDestinationUrl The URL that receives event data from Acoustic Exchange. Can be null if the endpoint does not exchange event data.
audienceSourceUrl 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.
audienceDestinationUrl The URL that receives audience data from Acoustic 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 IBM 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 deploymentID is the deployment that you defined when you generated the feature by calling POST v1/application/<applicationID>/deployment.

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 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.

Join The Discussion

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