Destinations

Destinations represent a location where content should be pushed to- we refer to this as a Target and it is enumerated consistently throughout the system.

Destinations generally contain information relating to API access, and identifying information for where on the Target platform the content is being pushed to. For example, a Facebook destination will have a ResourceId which relates to the Facebook page or timeline where the content will exist.

Custom Destinations are an exception in that they do not always determine a consistent location. It is possible for two publications to share a Custom destination, but push to completely separate platforms.


Destination Object

A Destination will contain the following:

{
    "id": "2fd62eed-24ea-4feb-a409-a1fe1704cc86",
    "name": "Example Destination",
    "target": 5,
    "configJson": "{...}",
    "client": "vualto-example",
    "active": false,
    "link": "...",
    "destinationProperties": []
}

The configJson property will vary between Target types and is used by the system to manage API access. Please refer to the below for details on required data.


Destination Metadata

There are a set of permitted values querying the API for Metadata. See query Target metadata and query Destination metadata.

Metadata:

  • YouTubeRegions
  • YouTubeVideoCategories
  • YouTubePrivacyStatus
  • YouTubeLicense
  • YouTubePlaylists
  • FacebookPages

Some data requires or supports extra data sent in the request, if providing the DestinationId this can be pre-populated from the existing data. This is as follows:

    YouTubeVideoCategories - requires `?youTubeRegions=X` to be specified, unless providing DestinationId.

Supported Actions

GET /destination/{id}

Get a Destination by its ID.

Response: 200 OK and JSON containing Destination object.


GET /destination/

Gets all Destinations (for the given Client).

Response: 200 OK and a JSON array containing multiple Destination objects.


GET /destination/metadata

Return the available metadata values for a given Target and metadata field.

Query Parameters:

    metadata: {string} - Required. Set it to be the name of the metadata field.

    target: {string} - Required. Set it to be the string value of your Target (i.e. 'Facebook').

    noCache: {bool} - Optional.

Refer to the above for permitted values.

Response: 200 OK and the following JSON structure:

{
    "name": "metadata",
    "target": 0,
    "Data": {
        "Key": "Value"
    }
}

GET /destination/metadata/{id}

Return the available metadata values for a given Destination and metadata field. This differs to the above as some metadata is dependent on the configured Destination (such as YouTube getting Categories based on the region).

Query Parameters:

    metadata: {string} - Required. Set it to be the name of the metadata field (see below).

    target: {string} - Required. Set it to be the string value of your Target (i.e. 'Facebook').

    noCache: {bool} - Optional.

Refer to the above for permitted values.

Response: 200 OK and the following JSON structure:

{
    "name": "metadata",
    "target": 0,
    "Data": {
        "Key": "Value"
    }
}

POST /destination/

Add a Destination.

Request Body:

{
    "name": "Example Destination",
    "target": "Custom",
    "configJson": "{...}"
}

The target property expects a string representation of the Target, rather than the enumerated version.

The configJson property will vary between Target types. Please refer to the below for details on required data.

Response: 201 Created and JSON of the Destination object.


PUT /destination/{id}

Updates the specified Destination.

{
    "name": "New Name",
    "target": "Facebook",
    "configJson": "{...}",
    "active": true
}

Response: 200 OK and JSON containing Destination object.


PUT /destination/state/{id}

Updates the active property for the specified Destination.

Query Parameters:

    active: {bool} - Required. bool value to set the active property to.

Response: 200 OK


PUT /destination/activate/{id}

Queries the activation process for the specified Destination.

For detailed information, refer to activation processes.

Response: 200 OK and the following JSON (details as example):

{
    "actionTitle": "Destination does not require action.",
    "actionDescription": "This is an example message. Destination is Active.",
    "actionRequired": false
}

DEL /destination/{id}

Deletes the specified Destination.

Response: 200 OK


DEL /destination/cache

Deletes the Destination(s) cache.

Query Parameters:

destinationId: {GUID} - Optional. GUID of the Destination to restrict cache deletion to a single Destination.

Response: 200 OK