Content Update API
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.
Important: Only call parameters that you need. Personalization Cloud operates off a set of APIs that support many applications and clients concurrently. Personalization Cloud may update and enhance these APIs at any time.
When initially integrating with the Content Update API or testing changes in usage of the Content Update API, requests should be made to the Staging Environment's instance of the API. Use the following base URL:
https://staging-gateway.richrelevance.com/contentupdate/v1
When it comes time to make the requests against the Production Environment, drop the "staging-" from the base URL:
https://gateway.richrelevance.com/contentupdate/v1
The endpoints that extend off of this URL are:
- {baseUrl}/oauth2/token : To authenticate and successfully call the other endpoints.
- {baseUrl} : To create and update content.
Security
POST {baseUrl}/oath2/token
The Content Update API uses the OAuth2 Client Credentials Grant Type to allow a client to authenticate. 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.
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.
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
| Name | Required or Optional | Description |
|---|---|---|
| grant_type | Required (string) | The access token type. This is always client_credentials |
| client_id | Required (string) | The client's ID |
| client_secret | Required (string) |
Good 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 will be unchanged. Only include properties that you want updated.
Request Legend
Note: All property names are case sensitive.
| Name | Required or Optional | Input | Description |
|---|---|---|---|
| id | Required | string - maxLength: 100 | |
| name | Optional | string - default: "{id}" - maxLength: 255 | |
| tags | Optional | array of string | |
| rating | Optional | number | |
| start_date | Optional | date-only - default: today | |
| end_date | Optional | date-only | |
| {property_name} | Required (Optional on PATCH) | array of string |
Example Requests
PUT
[{
"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/cont.../page/123.html"],
"size": ["100"]
},
{
"id": "124",
"name": "Free Shipping",
"tags": ["shipping", "checkout"],
"rating": "3.5",
"start_date": "2016-07-28",
"image_url": ["http://my.cdn.com/path/to/my/image/124.jpg"],
"click_thru": ["http://my.domain.com/path/to/my/cont.../page/124.html"],
"color": ["blue"]
}]
PATCH
[{
"id": "123",
"tags": ["fall", "fashion", "sale", "limited"]
},
{
"id": "124",
"rating": 3.4,
"click_thru": ["http://my.domain.com/path/to/my/cont...ge/123_v2.html"]
}]
Content Deletes
Content can be deleted.
DELETE {baseUrl}
Request Legend
Note: All property names are case sensitive.
| Name | Required or Optional | Input | Description |
|---|---|---|---|
| id | Required | string - maxLength: 100 |
The identifier of the product, category. |
Example Request for Products or Categories
[
{"id": "myContent1"},
{"id": "myContent2"},
...
]
Responses to Content Update Requests
Processing the request:
{
"trackingId": "YOUR_TRACKING_ID"
}
If your oauth2 token is invalid or expired:
{
"error_description": "The access token is invalid or has expired",
"error": "invalid_token"
}
If your json is malformed:
{
"code": 500,
"details": "{meaningful parsing exception}",
"message": "Internal Server Error",
"status": "error"
}
If your json is missing the id of an element:
{
"code": 400,
"details": "{}",
"message": "Bad Request",
"status": "error"
}
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