Skip to main content
RichRelevance

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. RichRelevance operates off a set of APIs that support many applications and clients concurrently. RichRelevance 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 RichRelevance 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 RichRelevance. 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)

A unique key to authorize a client app on behalf of the partner.

Example: clientSecret=wbhz6c41

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

Must be a unique ID.

NOTE: Forward slashes (/) are not supported in the ContentID field.

name Optional string - default: "{id}" - maxLength: 255

The name of the content as it will be displayed in recommendations on site and in the RichRelevance Dashboard.

Max length: 255 characters. If missing, name is not updated if the content is already in the system.

tags Optional array of string

List of strings that describe the piece of content.

A tag can be no longer than 100 characters long. If it is, we will truncate all characters after the 100th character. While there's no theoretical limit to how many tags a piece of content have, we recommend no more than 20 tags per content.   

rating Optional number

The rating for this content (specified by client). Usually this is generated by collecting the average of customer ratings/reviews.

start_date Optional date-only - default: today

When this content is available to be displayed. If not specified, it's available to be displayed any time. Format: yyyy-mm-dd. Defaults to today.

end_date Optional date-only

When does this content expire? Once expired we should not display it any longer. If not specified, it is available to be displayed indefinitely. Format: yyyy-mm-dd.

{property_name} Required (Optional on PATCH) array of string

Content attributes is where you will specify the variables needed to render a content. Things like image urls and landing page urls have to be passed in as attributes. We expect each piece of content to have a minimum of 1 attribute that allows us to render that piece of content back to the consumer. If a piece of content doesn't have any attributes then it will not be stored in our system.

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

  • Was this article helpful?