Content Update API

Overview

The Content Update API enables you to create, update, replace, and delete content items in the ADA content catalog. Use this API to keep your content catalog synchronized with changes made in your source systems.

Updates submitted through the API are processed and incorporated into the content catalog. Changes are not reflected in the Production environment immediately; instead, they are deployed according to the scheduled content catalog build and deployment process for your site.

Use this API to:

• Create content

• Update content

• Replace content

• Delete content

Base URLs

Staging Environment

Use this environment for initial integration and testing.

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

Production Environment

When you are ready to make requests against the Production environment, remove staging- from the base URL.

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

Example

https://gateway.richrelevance.com/content/v1/showcaseparent

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

IMPORTANT: Please note that the following endpoint has been deprecated: https://gateway.richrelevance.com/contentupdate/v1/{apikey}
Customers are advised to use the new endpoint.

Authentication to ADA Gateway

Authentication to the ADA API gateway is facilitated using OAuth 2.0 Client Credentials Grant authentication.

Note: Contact your ADA Customer Support Team to request a client_id and client_secret for your exclusive use.

ADA creates a unique client_id and client_secret for each site configured for a customer and shares them through the agreed communication channel.

The client_id and client_secret are required to obtain bearer tokens that are used to access the Content Update API. Bearer tokens have a system-defined time-to-live (TTL) validity period. Once TTL is reached, customer systems need to request a new bearer token with the provided client_id and client_secret.

Note: The bearer token Time to Live (TTL) for the Content Update service is set at 8 hours, equivalent to 28,800 seconds. To ensure uninterrupted utilization of the service without encountering authorization failures, it is recommended to request a new bearer token every 8 hours.

Creating Tokens

Hosts

Production

https://gateway.richrelevance.com/

Staging

https://staging-gateway.richrelevance.com/

Note: You must create separate tokens for each environment. Tokens created for one environment cannot be used in another environment.

To create a token, use the request syntax below:

POST https://<host>/content/v1/oauth2/token

Request Body

{
"grant_type": "client_credentials",
"client_id": "<client_id>",
"client_secret": "<client_secret>"
}

Note: Replace client_id and client_secret with the values provided by ADA.

Sample Request

curl --request POST \
--url https://gateway.richrelevance.com/content/v1/oauth2/token \
--header 'Content-Type: application/json' \
--data '{
"grant_type": "client_credentials",
"client_id": "cf5f05fb06390dea",
"client_secret": "dhd5qcuv8j5pltoo0l3rkcv15j",
}'

Sample Response

{
"token_type": "bearer",
"access_token": "HHwD4rzXDFwWv6o51WpPpaBJcY2TR0F1",
"expires_in": 28800
}

Error Responses

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

Requests to ADA Gateway Require the Bearer Token

For every Content Update API request, include the bearer token obtained during token creation in the Authorization header.

https://<host>/content/v1/<apiKey>

Authorization: Bearer <tokenValue>

Example: To update content in the catalog.

PUT https://gateway.richrelevance.com/content/v1/showcaseparent
Authorization: Bearer HHwD4rzXDFwWv6o51WpPpaBJcY2TR0F1

Example with cURL:

curl --location --request PUT \
'https://gateway.richrelevance.com/content/v1/showcaseparent' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer HHwD4rzXDFwWv6o51WpPpaBJcY2TR0F1' \
--data '[
  {
    "id": "product1",
    "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"]
  }
]'

Content Updates

Updating Content Parameters

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

PUT

Production

PUT https://gateway.richrelevance.com/content/v1/<apikey> 

Staging

PUT https://staging-gateway.richrelevance.com/content/v1/<apikey>

Adds a collection of new content to the content catalog or completely replaces content that matches the specified ID. When using PUT, omitted properties are removed from the content or reset to their default values.

PATCH

Production

PATCH https://gateway.richrelevance.com/content/v1/<apikey>

Staging

PATCH https://staging-gateway.richrelevance.com/content/v1/<apikey>

Updates one or more properties of existing content. Properties not included in the request remain unchanged. Include only the properties that you want to update.

Request Parameters

Note: Include only the parameters required for your request. All parameters and property names are case sensitive.

Example Requests

PUT

curl --location --request PUT \
'https://gateway.richrelevance.com/content/v1/showcaseparent' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer HHwD4rzXDFwWv6o51WpPpaBJcY2TR0F1' \
--data '[
  {
    "id": "product1",
    "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/content/v1/showcaseparent' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer HHwD4rzXDFwWv6o51WpPpaBJcY2TR0F1' \
--data '[
 [
{
   "id": "product1",
   "image_url": ["http://my.cdn.com/path/to/my/image/123.jpg","http://my.cdn.com/path/to/my/image/126.jpg"],
   "click_thru": ["http://my.domain.com/path/to/my/content/page/123.html","http://my.domain.com/path/to/my/content/page/125.html"]
 }
 ]

Content Deletes

Deletes content from the catalog.

DELETE https://<host>/content/v1/<apikey>

Request Parameters

Note: All property names are case sensitive.

Example Request

curl --location --request DELETE \
'https://gateway.richrelevance.com/content/v1/showcaseparent' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer HHwD4rzXDFwWv6o51WpPpaBJcY2TR0F1' \
--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

Check the following if you get 404 Not Found error:

• The API key is appended to the base URL.

• You are using the correct environment.

• The endpoint path is /content/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 use a POST request instead and specify the appropriate action query parameter while sending the same request body.

Mappings:

PUT https://gateway.richrelevance.com/content/v1/<apikey>
→ POST https://gateway.richrelevance.com/content/v1/<apikey>?action=replace

PATCH https://gateway.richrelevance.com/content/v1/<apikey>
→ POST https://gateway.richrelevance.com/content/v1/<apikey>?action=edit

DELETE https://gateway.richrelevance.com/content/v1/<apikey>
→ POST https://gateway.richrelevance.com/content/v1/<apikey>?action=delete