Content Update API

Overview

The Content Update API enables users to send content update requests as content catalog changes are made. The Production content catalog does not update immediately or directly. The updates are deployed to the Production environment at scheduled times that are based upon how long it takes to build and deploy a client’s content catalog model.

Use this API to:

• Create content

• Update content

• Replace content

• Delete content

IMPORTANT: Call only the parameters required for your request. All parameter and property names are case sensitive.
Algonomy operates off a set of APIs that support many applications and clients concurrently. Algonomy may update and enhance these APIs at any time.

Base URLs

Staging environment

Use this environment for initial integration and testing.

https://staging-gateway.richrelevance.com/contentupdate/v1/{apikey}

Production environment

When it comes time to make the requests against the Production environment, remove "staging-" from the base URL:

https://gateway.richrelevance.com/contentupdate/v1/{apikey}

Example

https://gateway.richrelevance.com/contentupdate/v1/dbc88fd3561a8ee1

Note: If the API key is not included in the path, the request may return a 404 Not Found error.

Authentication

The following endpoints are available under the base URL:

• {baseUrl}/oauth2/token — Used to authenticate and obtain an access token.

• {baseUrl} — Used to create, update, or delete content.

POST {baseUrl}/oauth2/token

The Content Update API uses the OAuth2 Client Credentials Grant Type for authentication. Contact your Algonomy team to request your OAuth2 credentials, a client_id and client_secret pair. Client_secrets need to be kept secure. They should never be shared, and only ever passed via HTTPS

To authenticate:

• Request an authorization bearer token by authenticating using your client credentials. The /oauth2/token endpoint must be called first to get a token that will give access to the other endpoints. Use the client id and secret sent to you by Algonomy.

• The response from this API will contain your token, which will be valid until it is manually revoked. The response will be provided as JSON. Use this token to authorize subsequent API requests.

• On all requests to the content API, pass an "Authorization: Bearer MY_TOKEN" header. When the token expires you will need to get a new one using your client id and secret again.

Request Legend

Example Token Response

{
"token_type": "bearer",
"access_token": "AABBCCDD"
}

Error Responses

{
"error_description": "Invalid client authentication",
"error": "invalid_client"
}
{
"error_description": "Invalid grant_type",
"error": "unsupported_grant_type"
}

Content Updates

Updating Content Parameters

Both PUT and PATCH can be used to update content in the catalog.

PUT {baseUrl}

PATCH {baseUrl}

PUT: Put a collection of new content into the content catalog or fully replace content with the matching id in the catalog. Updating a content using PUT will remove omitted properties from the content or set them to defaults.

PATCH: Update a property or properties of a collection of content.  Properties not included remain unchanged.  Only include properties that you want to update.

Request Legend

Note: All property names are case sensitive.

Example Requests

PUT

curl --location --request PUT \
'https://gateway.richrelevance.com/contentupdate/v1/dbc88fd3561a8ee1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sNi7j0BdMRo0jHaD8TfzUL7I6Q2MImtA' \
--data '[
  {
    "id": "123",
    "name": "Fall Fashion",
    "tags": ["fall", "fashion", "sale"],
    "rating": 4.0,
    "start_date": "2016-08-28",
    "end_date": "2016-11-28",
    "image_url": ["http://my.cdn.com/path/to/my/image/123.jpg"],
    "click_thru": ["http://my.domain.com/path/to/my/content/page/123.html"],
    "size": ["100"]
  }
]'

PATCH

curl --location --request PATCH \
'https://gateway.richrelevance.com/contentupdate/v1/dbc88fd3561a8ee1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sNi7j0BdMRo0jHaD8TfzUL7I6Q2MImtA' \
--data '[
  {
    "id": "123",
    "tags": ["fall", "fashion", "sale", "limited"]
  }
]'

Content Deletes

Deletes content from the catalog.

DELETE {baseUrl}

Request Legend

Note: All property names are case sensitive.

Example Request

curl --location --request DELETE \
'https://gateway.richrelevance.com/contentupdate/v1/dbc88fd3561a8ee1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sNi7j0BdMRo0jHaD8TfzUL7I6Q2MImtA' \
--data '[
  { "id": "myContent1" },
  { "id": "myContent2" }
]'

Responses to Content Update Requests

Successful Processing

{
"trackingId": "YOUR_TRACKING_ID"
}

Invalid or Expired Token

{
"error_description": "The access token is invalid or has expired",
"error": "invalid_token"
}

Malformed JSON

{
  "code": 500,
  "details": "{meaningful parsing exception}",
  "message": "Internal Server Error",
  "status": "error"
}

Missing Required ID

{
  "code": 400,
  "details": "{}",
  "message": "Bad Request",
  "status": "error"
}

Troubleshooting

404 Not Found

Check the following:

• The API key is appended to the base URL.

• You are using the correct environment (Staging or Production).

• The endpoint path is /contentupdate/v1/{apiKey}.

• Your OAuth token is valid.

Appendix

Q: My REST client does not support sending a body in a DELETE request, is there an alternative?

A: Yes. You can do a POST instead with the query param "action=delete" using the same body that you would for a DELETE request. There are POST alternatives for each of the PUT, PATCH and DELETE endpoints.

Mapping:

PUT {baseUrl} -> POST {baseUrl}?action=replace

PATCH {baseUrl} -> POST {baseUrl}?action=edit

DELETE {baseUrl} -> POST {baseUrl}?action=delete