The Dynamic Content Management API helps you integrate your back end systems with Dynamic Content.

The API is designed for building back-office applications and you can use it for webhook integrations, content automation apps, or to integrate with your existing back end services.

To use the API, you'll need a client ID and secret. The authorization section below explains how to use the client ID and secret to obtain an access token that must be included with each request.

Dynamic Content uses OAuth2 to authorize access to the Dynamic Content management API.

To use the API you will need an API key and secret. These credentials will be provided to you by Amplience at the beginning of your project, or you can request them from Amplience support. Your API key will define the resources to which you have access.

Your API key and secret are used to obtain an access token from the Amplience authorization service. This token must be included in the authorization header of all requests to the Dynamic Content management API and is set to expire after a set time period, generally 300 seconds.

To get an authorization token, send a POST request to the Amplience authorization server at https://auth.amplience.net as follows.

Request

POST  https://auth.amplience.net/oauth/token

Headers

Parameters

The parameters should be URL encoded and included in the body of the request:

client_id={yourclientid}&client_secret={yoursecret}&grant_type=client_credentials

Replace {yourclientid} and {yoursecret} with your client id and secret.

Response

Status codes

Response body

If the clientID and secret are valid, the response body will be returned as in the example below.

Note that the example access_token has been truncated.

{
  "access_token": "eyJraWQiOiJhbXBsaWVuY2UtdG9rZW4tc2lnbmluZy1rZXkiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJhbXBsaWVuY2UuY29tIiwiZXhwIjoxNTUzODY4NjIyLCJqdGkiOiJMT2pvZ1dtMFM3TkRNT2VsTk96cWVnIiwiaWF0IjoxNTUzODY3MzYyLCJzd…",
  "session_expires_in": 0,
  "expires_in": 300
}

You will need to save the access token and include it in requests to the API. If the token has expired, request another token from the authorization service.

The Dynamic Content management SDK contains code to help you manage the access token.

To make a request to the Dynamic Content management API, for example to list all the hubs you have access to you would send a request such as:

GET https://api.amplience.net/v2/content/hubs

In the request header you must set the Authorization format to "Bearer" and include the access token:

Authorization : Bearer {access_token}

Replace {access_token} with the access token returned by the authorization service.

If the access token is valid, then the request is processed and the response is returned.

Resources can usually be retrieved using a /resource-types/:id endpoint. Collection resources will always be pluralised, regardless of how they are accessed. In cases where resources are nested under a parent resource, and this context is necessary for the request, this information is included in the routing. For example, while a Content Repository can be retrieved by id using GET /content-repositories/:id, to create a new Content Repository it is necessary to supply the ID of the parent Hub, so the route would take the form POST /hubs/:hubId/content-repositories.

Resources are returned in the HAL format, which provides a representation of HATEOAS information in JSON. This allows for discoverability of endpoints from responses, as a response for a resource will contain links to related resources and actions. Links are contained within a _links object, and are keyed by name. In some cases, such as resource listing or search results, linked resources are included in the response inside an _embedded object, allowing multiple resource to be returned within the same response body.

Response codes for the API are described in the table below.

If an error occurs, the response body contains a JSON object containing an errors array. This will contain one or more error objects, containing a message field describing the error, and context specific metadata relating to this instance of the error.

HTTP/1.1 409 Conflict
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 145

{
  "errors" : [ {
    "entity" : "Hub",
    "property" : "name",
    "invalidValue" : "anya-finn",
    "message" : "name must be unique"
  } ]
}

When updating a resource, the PATCH method is used. When making a PATCH request, any fields specified in the request will overwrite their associated values in the stored resource, but omitted fields will remain unchanged. This is in contrast to the PUT method, which would set omitted fields to null, and is not supported in this API. When making a PATCH request to a resource containing nested JSON objects, it is important to note that child objects are replaced completely, and do not inherit the PATCH functionality of the root object.

For example, given a stored resource in the format:

{
  "foo": {
    "bar": "abc",
    "baz": "xyz"
  },
  "bar": "123"
}

When the following request body is used in a PATCH request:

{
  "foo": {
    "bar": "def"
  }
}

The resource would be transformed to the following:

{
  "foo": {
    "bar": "def"
  },
  "bar": "123"
}

Payload Considerations

When submitting a JSON payload to the API, the first complete JSON object in the body will be accepted, and any additional information will be discarded. For example:

{
  "foo": {
    "bar": "def"
  },
  "unknownProperty": "will be ignored"
}

In the above example, there is an extra closing brace and additional characters that follow a valid JSON object. Any extra input characters like this will be ignored by the API.

Administration allows you to add or revoke permissions for users and manage access to resources.

A simple query syntax is provided to allow full text search on content items. Several characters have special meaning and are reserved:

Table 2. Reserved Search Characters

Please note that the text search is case insensitive, and will only display content items within the hub. See the following examples for an explanation of the query syntax:

Table 3. Text Search Examples