Sites resource (Data API 19.10)

Summary

Http Method Resource Description
GET /sites Action to get all existing sites.
GET /sites/{site_id} Action to read an existing site.
GET /sites/{site_id}/ab_tests Action to get all the A/B tests with searching.
GET /sites/{site_id}/ai/recommender_names Get a list of available AI recommenders. Recommenders are configured in the Einstein configurator and are required with AI recommendation API requests.
PUT /sites/{site_id}/cartridges Overwrite cartridge path.
POST /sites/{site_id}/cartridges Add a cartridge to current cartridge path.
DELETE /sites/{site_id}/cartridges/{cartridge_name} Remove a cartridge from cartridge path.
GET /sites/{site_id}/custom_objects/{object_type}/{key} Reads a site specific Custom Object with a given object type ID and a value for the key attribute of the object which represents its unique identifier.
PUT /sites/{site_id}/custom_objects/{object_type}/{key} Creates a site specific Custom Object from request body for the specified site. Note that an existing Custom Object for the site, with the same key, will be overwritten by this action.
DELETE /sites/{site_id}/custom_objects/{object_type}/{key} Deletes a site specific Custom Object. If the Custom Object does not exist, this will do nothing. Note that the customization scripts are only called, if the Custom Object does exist.
PATCH /sites/{site_id}/custom_objects/{object_type}/{key} Updates a site specific Custom Object with information from request body. Note that only mentioned attributes will be updated and the key attribute is ignored. All other attributes will be left unattended.
GET /sites/{site_id}/locale_info/locales Action to get the set of locales with the system given a site.
GET /sites/{site_id}/site_preferences/preference_groups/{group_id}/{instance_type} For the specified site and instance, read the custom preferences in the preference group. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.
PATCH /sites/{site_id}/site_preferences/preference_groups/{group_id}/{instance_type} For the specified site and instance, update one or more custom preferences in the preference group. Preferences of type password cannot be set to "************" since it is a reserved value.
GET /sites/{site_id}/slot_configurations Action to get all the slot configurations with no filtering.

Get Sites

Action to get all existing sites.

Url

GET https://hostname:port/dw/data/v19_10/sites?start={Integer}&count={Integer}&select={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

Sites

Query Parameters

Parameter Type Description Constraints
count Integer Optional count for retrieving only a subset of the items (default is 25).  
select String The property selector.  
start Integer Optional start index for retrieving the items from a given index (default 0).  

Sample

REQUEST:
GET  /s/-/dw/data/v19_10/sites?select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
{
  "_v" : "19.10",
  "count" : 2,
  "data" : [ 
    {
        "_v" : "19.10",
        "_type" : "site",
        "customer_list_link" : {
            "_type" : "customer_list_link",
            "customer_list_id" : "SiteGenesis",
            "link" : "https://example.com/s/-/dw/data/v19_10/customer_lists/SiteGenesis"
        },
        "description" : {
            "default": "Prototypical site used for starting point",
        }
        "display_name" : {
            "default": "Site Genesis",
        }
        "id" : "SiteGenesis",
        "in_deletion": false,
        "link" : "https://example.com/s/-/dw/data/v19_10/sites/SiteGenesis",
        "storefront_status": "online"
    },
    {
        "_v" : "19.10",
        "_type" : "site",
        "customer_list_link" : {
            "_type" : "customer_list_link",
            "customer_list_id" : "MyCustomerList",
            "link" : "https://example.com/s/-/dw/data/v19_10/customer_lists/MyCustomerList"
        },
        "description" : {
            "default": "A site that sells products",
        }
        "display_name" : {
            "default": "My Site",
        }
        "id" : "MySite",
        "in_deletion": false,
        "link" : "https://example.com/s/-/dw/data/v19_10/sites/MySite",
        "storefront_status": "online"
    }
  ],
  "select": "**",
  "start" : 0,
  "total" : 2
}

Get site

Action to read an existing site.

Url

GET https://hostname:port/dw/data/v19_10/sites/{site_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

Site

Path Parameters

Parameter Type Description Constraints
site_id String the id of the site minLength=1

Sample

REQUEST:
GET /s/-/dw/data/v19_10/sites/SiteGenesis HTTP/1.1
Host: example.com
Authorization:Bearer ac734607-c966-44fb-8739-8ea413a2c0a5
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "19.10",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "site",
   "customer_list_link" : 
   {
      "_type" : "customer_list_link",
      "customer_list_id" : "SiteGenesis",
      "link" : "https://example.com/s/-/dw/data/v19_10/customer_lists/SiteGenesis"
   },
   "description" : "Site's site used for WAPI integration test.",
   "id" : "SiteGenesis"
}

# in case of failure (SecureCommunicationRequired, i.e. no http):

RESPONSE:
HTTP/1.1 403 Forbidden
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "19.10",
   "fault" : 
   {
      "type" : "SecureCommunicationRequiredException",
      "message" : "A secure connection is required."
   }
}

# in case of failure (SiteNotFound, i.e. invalid site id):

RESPONSE:
HTTP/1.1 404 Forbidden
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "19.10",
   "fault" : 
   {
      "type" : "SiteNotFoundException",
      "message" : "No site with ID 'foobar' was found."
   }
}

Get AB/Tests

Action to get all the A/B tests with searching.

Url

GET https://hostname:port/dw/data/v19_10/sites/{site_id}/ab_tests?start={Integer}&count={Integer}&select={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

AbTests

Path Parameters

Parameter Type Description Constraints
site_id String ID of the site that the A/B tests are contained within. mandatory=true, maxLength=256, minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
count Integer Optional count for retrieving only a subset of the items (default is 25). minIntegerValue=0
select String The property selector.  
start Integer Optional start index for retrieving the items from a given index (default 0). minIntegerValue=0

Sample

REQUEST:
GET /s/-/dw/data/v19_10/sites/SiteGenesis/ab_tests?select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8

{
  "_v" : "19.10",
  "_type" : "ab_test_search_result",
  "count" : 2,
  "data" : [
    {
       "_v" : "19.10",
       "_type" : "ab_tests",
       "_resource_state":"c2309jd239jdrifj3ui4fn",
       "customer_groups" : 
       [
          "abtest_customer_group"
       ],
       "description" : "my abtest1 description",
       "email_addresses" : 
       [
          "[email protected]"
       ],
       "enabled" : true,
       "end_date" : "2015-07-31T23:09:08.000Z",
       "expiration_type" : "session",
       "id" : "my-abtest1",
       "key_metric_id" : "abtest_key_metric_id",
       "link" : "https://example.com/s/-/dw/data/v19_10/sites/SiteGenesis/ab_tests/my-abtest1",
       "paused" : true,
       "start_date" : "2015-04-01T11:30:15.000Z",
       "tags" : 
       [
          "abtest_tag"
       ],
       "test_groups" : 
       [
          {
             "_type" : "ab_test_group",
             "allocation" : 20,
             "custom_experience" : false,
             "id" : "Control"
          },
          {
             "_type" : "ab_test_group",
             "allocation" : 40,
             "custom_experience" : false,
             "description" : "A description",
             "id" : "Test Segment A"
          },
          {
             "_type" : "ab_test_group",
             "allocation" : 40,
             "custom_experience" : false,
             "id" : "Test Segment B"
          }
       ],   
       "trigger" : 
       {
          "_type" : "ab_test_trigger",
          "is_pipeline_based" : false,
          "trigger_type" : "immediately"
       }    
    },
    {
       "_v" : "19.10",
       "_type" : "ab_test",
       "_resource_state":"9g9jrfc93jr03fr09sdcjk",
       "customer_groups" : 
       [
          "abtest_customer_group"
       ],
       "description" : "my abtest2 description",
       "email_addresses" : 
       [
          "[email protected]"
       ],
       "enabled" : true,
       "end_date" : "2015-07-31T23:09:08.000Z",
       "expiration_type" : "session",
       "id" : "my-abtest2",
       "key_metric_id" : "abtest_key_metric_id",
       "link" : "https://example.com/s/-/dw/data/v19_10/sites/SiteGenesis/ab_tests/my-abtest2",
       "paused" : true,
       "start_date" : "2015-04-01T11:30:15.000Z",
       "tags" : 
       [
          "abtest_tag"
       ],
       "test_groups" : 
       [
          {
             "_type" : "ab_test_group",
             "allocation" : 20,
             "custom_experience" : false,
             "id" : "Control"
          },
          {
             "_type" : "ab_test_group",
             "allocation" : 80,
             "custom_experience" : false,
             "id" : "Test Segment B"
          }
       ],   
       "trigger" : 
       {
          "_type" : "ab_test_trigger",
          "is_pipeline_based" : true,
          "trigger_type" : "pipeline_call",
          "pipeline_calls" :
          [
              "My-Pipeline"
          ]
       }
    }
  ],
  "select": "**",
  "start" : 0,
  "total" : 2
}

Get recommenders

Get a list of available AI recommenders. Recommenders are configured in the Einstein configurator and are required with AI recommendation API requests.

Url

GET https://hostname:port/dw/data/v19_10/sites/{site_id}/ai/recommender_names

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

RecommendersResult

Path Parameters

Parameter Type Description Constraints
site_id String Site ID to get a list of recommenders for. mandatory=true, maxLength=256, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 CQuotientException

originalStatusCode (Integer)

responseBody (String)

If CQuotient responds with a non-success status code.
404 SiteNotFoundException

siteId (String)

If the given site does not exist.

Sample

REQUEST:
GET /dw/data/v19_10/sites/SiteGenesis/ai/recommender_names HTTP/1.1
Host: example.com
Authorization: Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type: application/json

# in case of success

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 57

{
  "_v": "19.10",
  "_type": "recommenders_result",
  "recommenders": [
    {
      "_type": "recommender",
      "description": "Recommender for Alternate Products on a PDP",
      "name": "Alternate-Product-to-Product"
    },
    {
      "_type": "recommender",
      "description": "** for shared demo **",
      "name": "topsellers"
    },
    {
      "_type": "recommender",
      "description": "Shopper, Recently-Viewed",
      "name": "recently-viewed"
    },
    {
      "_type": "recommender",
      "description": "demo",
      "name": "demo"
    }
  ]
}

# in case of failure

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 57

{
  "_v": "19.10",
  "fault": {
    "arguments": {
      "siteId": "UnknownSite"
    },
    "type": "SiteNotFoundException",
    "message": "No site with ID 'UnknownSite' was found."
  }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 57

{
  "_v": "19.10",
  "fault": {
    "arguments": {
      "originalStatusCode": "400",
      "responseBody": "{\"code\":\"1\",\"message\":\"The given site id is not valid\"}"
    },
    "type": "CQuotientException",
    "message": "Proxy error ('400'): '{"code":"1","message":"The given site id is not valid"}'."
  }
}

Overwrite cartridge path

Overwrite cartridge path.

Url

PUT https://hostname:port/dw/data/v19_10/sites/{site_id}/cartridges

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CartridgePathCreateRequest

Response Document

CartridgePathApiResponse

Path Parameters

Parameter Type Description Constraints
site_id String ID of the site. mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCartridgePathException

targetCartridge (String)

Indicates that the cartridge path is invalid
404 SiteNotFoundException

siteId (String)

Indicates that site specified with the given id is unknown.

Sample

Request
PUT /s/-/dw/data/v19_10/sites/{site-id}/cartridges HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache
{
    "cartridges": "new_cartridges1:new_cartridges2"
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
    "_v": "19.10",
    "_type": "cartridge_path_api_response",
    "cartridge_path": "new_cartridges1:new_cartridges2:core",
    "site_id": "SiteGenesis"
}

# in case of failure when site not found
RESPONSE:
HTTP/1.1 404
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v": "19.10",
    "fault": {
        "arguments": {
            "siteId": "unknownSite"
        },
        "type": "SiteNotFoundException",
        "message": "No site with ID 'SiteGenesis1' was found."
    }
}

# in case of failure when site not found
RESPONSE:
HTTP/1.1 400
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v": "19.10",
    "fault": {
        "arguments": {
            "cartridge": "1BadCartidgeName:2BadCartidgeName"
        },
        "type": "InvalidCartridgePathException",
        "message": "Invalid cartridge path '1BadCartidgeName:2BadCartidgeName'. Cartridge names may only contain letters, numbers, or \"_\", must start with a letter, and be separated by \":\". "
    }
}

Add a cartridge to cartridge path

Add a cartridge to current cartridge path.

Url

POST https://hostname:port/dw/data/v19_10/sites/{site_id}/cartridges

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CartridgePathAddRequest

Response Document

CartridgePathApiResponse

Path Parameters

Parameter Type Description Constraints
site_id String ID of the site. mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidOperationException

targetCartridge (String)

The error may happen when position is either 'after' or 'before'. It indicates either target cartridge is not a existing custom cartridge.
400 CartridgeAlreadyExistException

targetCartridge (String)

Indicates that the cartridge already exist in cartridge path
400 InvalidCartridgeException

targetCartridge (String)

Indicates that the cartridge name is invalid
404 SiteNotFoundException

siteId (String)

Indicates that site specified with the given id is unknown.

Sample

Request

# Example 1: Add to first

POST /s/-/dw/data/v19_10/sites/SiteGenesis/cartridges HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache

{
    "name": "new_cartridge",
    "position": "first"
}

# Example 2: Add to last
POST /s/-/dw/data/v19_10/sites/SiteGenesis/cartridges HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache

{
    "name": "new_cartridge",
    "position": "last"
}

# Example 3: Add Before
POST /s/-/dw/data/v19_10/sites/SiteGenesis/cartridges HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache

{
    "name": "new_cartridge",
    "position": "before",
    "target" : "custom_cartridge_1"
}


# Example 4: Add After
POST /s/-/dw/data/v19_10/sites/SiteGenesis/cartridges HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache

{
    "name": "new_cartridge",
    "position": "after",
    "target" : "custom_cartridge_1"
}


# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
    "_v": "19.10",
    "_type": "cartridge_path_api_response",
    "cartridges": "new_cartridge:custom_cartridge_1:custom_cartridge_2:core",
    "site_id": "SiteGenesis"
}

# in case of failure when site not found:
RESPONSE:
HTTP/1.1 404
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v": "19.10",
    "fault": {
        "arguments": {
            "siteId": "unknownSite"
        },
        "type": "SiteNotFoundException",
        "message": "No site with ID 'SiteGenesis1' was found."
    }
}


# in case of failure when cartridge already exist:
RESPONSE:
HTTP/1.1 400
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v": "19.10",
    "fault": {
        "arguments": {
            "cartridge": "new_cartridge"
        },
        "type": "CartridgeAlreadyExistException",
        "message": "Cartridge 'new_cartridge' already exists."
    }
}

# in case of failure when cartridge is invalid:
RESPONSE:
HTTP/1.1 400
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v": "19.10",
    "fault": {
        "arguments": {
            "cartridge": "123test"
        },
        "type": "InvalidCartridgeException",
        "message": "Invalid cartridge '123test'. Cartridge names may only contain letters, numbers, or \"_\", must start with a letter."
    }
}

# in case of failure when target cartridge is invalid
# Target cartridge is invalid when
# 1. target cartridge is null 2. target cartridge is a system cartridge 3. target cartridge doesn't exist
RESPONSE:
HTTP/1.1 400
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v": "19.10",
    "fault": {
        "arguments": {
            "target_cartridge": "core"
        },
        "type": "InvalidOperationException",
        "message": "Invalid operation on cartridge 'core'. The operation is only allowed on existing custom cartridge."
    }
}

Remove a cartridge from cartridge path

Remove a cartridge from cartridge path.

Url

DELETE https://hostname:port/dw/data/v19_10/sites/{site_id}/cartridges/{cartridge_name}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

CartridgePathApiResponse

Path Parameters

Parameter Type Description Constraints
cartridge_name String request body mandatory=true, minLength=1, nullable=false
site_id String ID of the site. mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidOperationException

targetCartridge (String)

It indicates either the cartridge doesn't exist in cartridge path or the cartridge can not be deleted (e.g. System Cartridge).
404 SiteNotFoundException

siteId (String)

Indicates that site specified with the given id is unknown.

Sample

Request
DELETE /s/-/dw/data/v19_10/sites/SiteGenesis/cartridges/customer_cartridge_2 HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
    "_v": "19.10",
    "_type": "cartridge_path_api_response",
    "cartridges": "custom_cartridge_1:custom_cartridge_3:core",
    "site_id": "SiteGenesis"
}

# in case of failure:
RESPONSE:
HTTP/1.1 400
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v": "19.10",
    "fault": {
        "arguments": {
            "target_cartridge": "core"
        },
        "type": "InvalidOperationException",
        "message": "Invalid operation on cartridge 'core'. The operation is only allowed on existing custom cartridge."
    }
}

Read site specific Custom Object

Reads a site specific Custom Object with a given object type ID and a value for the key attribute of the object which represents its unique identifier.

Url

GET https://hostname:port/dw/data/v19_10/sites/{site_id}/custom_objects/{object_type}/{key}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

CustomObject

Path Parameters

Parameter Type Description Constraints
key String the key attribute value of the Custom Object mandatory=true, minLength=1, nullable=false
object_type String the ID of the object type mandatory=true, minLength=1, nullable=false
site_id String the ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MalformedKeyParameterException

value (String)

parameter (String)

If the object key must be an integer, but the path parameter has an invalid format
404 CustomObjectNotFoundException

key (String)

objectType (String)

For an unknown object key
404 ObjectTypeNotFoundException

objectType (String)

For an unknown object type ID

Sample

REQUEST:
GET /s/-/dw/data/v19_10/sites/SiteGenesis/custom_objects/my_object_type/key_0815 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
  "_v" : "19.10",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "custom_object",
   "object_type":"my_object_type",
   "key_property":"key_attribute",
   "c_boolean":true,
   "c_date":"2015-02-03T00:00:00.000Z",
   "c_email":"[email protected]",
   "c_integer":42,
   "c_number":42.0,
   "c_string":"some text"
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Requested resource not found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.10",
  "fault":
  {
    "type":"CustomObjectNotFoundException",
    "message":"No custom object with key 'key_0815' for object type 'my_object_type' was found.
  }
}

Create site specific Custom Object

Creates a site specific Custom Object from request body for the specified site. Note that an existing Custom Object for the site, with the same key, will be overwritten by this action.

Url

PUT https://hostname:port/dw/data/v19_10/sites/{site_id}/custom_objects/{object_type}/{key}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CustomObject

Response Document

CustomObject

Path Parameters

Parameter Type Description Constraints
key String the key attribute value of the Custom Object mandatory=true, minLength=1, nullable=false
object_type String the ID of the object type mandatory=true, minLength=1, nullable=false
site_id String the ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MalformedKeyParameterException

value (String)

parameter (String)

If the object key must be an integer, but the path parameter has an invalid format
404 CustomObjectNotFoundException

key (String)

objectType (String)

For an unknown object key
404 ObjectTypeNotFoundException

objectType (String)

For an unknown object type ID

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.object.beforePut

beforePut (create : CustomObject ) : Status

The function is called before the custom object is created with create document.

Parameters:
create - the create document, may be null
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.object.afterPut

afterPut (customObject : CustomObject , create : CustomObject ) : Status

The function is called after the custom object was created with create document.

Parameters:
customObject - the created custom object
create - the create document, may be null
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PUT /s/-/dw/data/v19_10/sites/SiteGenesis/custom_objects/my_object_type/key_0815 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
{
   "c_boolean":true,
   "c_date":"2015-02-03T00:00:00.000Z",
   "c_email":"[email protected]",
   "c_integer":42,
   "c_number":42.0,
   "c_string":"some text"
}

# in case of success:

RESPONSE:
HTTP/1.1 201 CREATED
Location: https://example.com/s/-/dw/data/v19_10/sites/SiteGenesis/custom_objects/my_object_type/key_0815
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
  "_v" : "19.10",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
  "_type" : "custom_object",
  "object_type":"my_object_type",
  "key_property":"key_attribute",
  "key_value_string":"key_0815",
  "c_boolean":true,
  "c_date":"2015-02-03T00:00:00.000Z",
  "c_email":"[email protected]",
  "c_integer":42,
  "c_number":42.0,
  "c_string":"some text"
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Requested resource not found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.10",
  "fault":
  {
    "type":"ObjectTypeNotFoundException",
    "message":"No object type with ID 'my_object_type' was found."
  }
}

Delete site specific Custom Object

Deletes a site specific Custom Object. If the Custom Object does not exist, this will do nothing. Note that the customization scripts are only called, if the Custom Object does exist.

Url

DELETE https://hostname:port/dw/data/v19_10/sites/{site_id}/custom_objects/{object_type}/{key}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
key String the key attribute value of the Custom Object mandatory=true, minLength=1, nullable=false
object_type String the ID of the object type mandatory=true, minLength=1, nullable=false
site_id String the ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MalformedKeyParameterException

value (String)

parameter (String)

If the object key must be an integer, but the path parameter has an invalid format
404 ObjectTypeNotFoundException

objectType (String)

For an unknown object type ID

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.object.beforeDelete

beforeDelete (customObject : CustomObject ) : Status

The function is called before the custom object is removed.

Parameters:
create - the create document
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.object.afterDelete

afterDelete () : Status

The function is called after the custom object was deleted.

Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /s/-/dw/data/v19_10/sites/SiteGenesis/custom_objects/my_object_type/key_0815 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

# in case of success:

RESPONSE:
HTTP/1.1 204 OK

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Requested resource not found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.10",
  "fault":
  {
    "type":"ObjectTypeNotFoundException",
    "message":"No object type with ID 'my_object_type' was found."
  }
}

Update site specific Custom Object

Updates a site specific Custom Object with information from request body. Note that only mentioned attributes will be updated and the key attribute is ignored. All other attributes will be left unattended.

Url

PATCH https://hostname:port/dw/data/v19_10/sites/{site_id}/custom_objects/{object_type}/{key}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CustomObject

Response Document

CustomObject

Path Parameters

Parameter Type Description Constraints
key String the key attribute value of the Custom Object mandatory=true, minLength=1, nullable=false
object_type String the ID of the object type mandatory=true, minLength=1, nullable=false
site_id String the ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MalformedKeyParameterException

value (String)

parameter (String)

If the object key must be an integer, but the path parameter has an invalid format
404 CustomObjectNotFoundException

key (String)

objectType (String)

For an unknown object key
404 ObjectTypeNotFoundException

objectType (String)

For an unknown object type ID

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.object.beforePatch

beforePatch (customObject : CustomObject , update : CustomObject ) : Status

The function is called before the custom object is updated with update document.

Parameters:
update - the update document
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.object.afterPatch

afterPatch (customObject : CustomObject , create : CustomObject ) : Status

The function is called after the custom object was updated with update document.

Parameters:
customObject - the updated custom object
update - the update document
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /s/-/dw/data/v19_10/sites/SiteGenesis/custom_objects/my_object_type/key_0815 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
{
   "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
   "c_boolean":true,
   "c_date":"2015-02-03T00:00:00.000Z",
   "c_email":"[email protected]",
   "c_integer":42,
   "c_number":42.0,
   "c_string":"some text"
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "19.10",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "custom_object",
   "object_type":"my_object_type",
   "key_property":"key_attribute",
   "c_boolean":true,
   "c_date":"2015-02-03T00:00:00.000Z",
   "c_email":"[email protected]",
   "c_integer":42,
   "c_number":42.0,
   "c_string":"some text"
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Requested resource not found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.10",
  "fault":
  {
    "type":"CustomObjectNotFoundException",
    "message":"No custom object with key 'key_0815' for object type 'my_object_type' was found.
  }
}

Get Locales

Action to get the set of locales with the system given a site.

Url

GET https://hostname:port/dw/data/v19_10/sites/{site_id}/locale_info/locales?include_all={Boolean}&id={String}&select={String}&start={Integer}&count={Integer}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

LocaleResult

Path Parameters

Parameter Type Description Constraints
site_id String Only locales specified for the site are returned minLength=1

Query Parameters

Parameter Type Description Constraints
count Integer the count of the records to return in this page. Default is 25.  
id String optional locale to return by id. If specified, that locale is looked up and returned, otherwise the list is returned.  
include_all Boolean true if we want to include all the locales. Default is false.  
select String the set of fields to return from the request. Default is only the locale id.  
start Integer the start index for paging. Default is 0.  

Sample

REQUEST:
GET /s/-/dw/data/v19_10/sites/SiteGenesis/locale_info/locales?select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "19.10",
   "_type" : "locale_result",
   "count" : 4,
   "hits" :
   [
      {
         "_type" : "locale",
         "active" : true,
         "country" : "",
         "default" : true,
         "display_country" : "",
         "display_language" : "",
         "display_name" : "default",
         "id" : "default",
         "iso3_country" : "",
         "iso3_language" : "",
         "language" : "",
         "name" : "default"
      },
      {
         "_type" : "locale",
         "active" : true,
         "country" : "",
         "default" : false,
         "display_country" : "",
         "display_language" : "español",
         "display_name" : "español",
         "id" : "es",
         "iso3_country" : "",
         "iso3_language" : "spa",
         "language" : "es",
         "name" : "Spanish"
      }
   ],
   "select" : "(**)",
   "start" : 0,
   "total" : 4
}

REQUEST:
GET /s/-/dw/data/v19_10/sites/SiteGenesis/locale_info/locales?include_all=true&select=(**)&start=3&count=8 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "19.10",
   "_type" : "locale_result",
   "count" : 8,
   "hits" : [
      {
         "_type" : "locale",
         "active" : true,
         "country" : "",
         "default" : true,
         "display_country" : "",
         "display_language" : "",
         "display_name" : "default",
         "id" : "default",
         "iso3_country" : "",
         "iso3_language" : "",
         "language" : "",
         "name" : "default"
      },
      {
         "_type" : "locale",
         "active" : false,
         "country" : "",
         "default" : false,
         "display_country" : "",
         "display_language" : "Nederlands",
         "display_name" : "Nederlands",
         "id" : "nl",
         "iso3_country" : "",
         "iso3_language" : "nld",
         "language" : "nl",
         "name" : "Dutch"
      },
      {
         "_type" : "locale",
         "active" : true,
         "country" : "",
         "default" : false,
         "display_country" : "",
         "display_language" : "English",
         "display_name" : "English",
         "id" : "en",
         "iso3_country" : "",
         "iso3_language" : "eng",
         "language" : "en",
         "name" : "English"
      },
      {
         "_type" : "locale",
         "active" : false,
         "country" : "CA",
         "default" : false,
         "display_country" : "Canada",
         "display_language" : "English",
         "display_name" : "English (Canada)",
         "id" : "en-CA",
         "iso3_country" : "CAN",
         "iso3_language" : "eng",
         "language" : "en",
         "name" : "English (Canada)"
      },
      {
         "_type" : "locale",
         "active" : true,
         "country" : "US",
         "default" : false,
         "display_country" : "United States",
         "display_language" : "English",
         "display_name" : "English (United States)",
         "id" : "en-US",
         "iso3_country" : "USA",
         "iso3_language" : "eng",
         "language" : "en",
         "name" : "English (United States)"
      }
   ],
   "include_all": true,
   "select" : "(**)",
   "start" : 0,
   "total" : 8
}

REQUEST:
GET /s/-/dw/data/v19_10/sites/SiteGenesis/locale_info/locales?id=en-US&select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "19.10",
   "_type" : "locale_result",
   "count" : 1,
   "hits" : [
      {
         "_type" : "locale",
         "active" : true,
         "country" : "US",
         "default" : false,
         "display_country" : "United States",
         "display_language" : "English",
         "display_name" : "English (United States)",
         "id" : "en-US",
         "iso3_country" : "USA",
         "iso3_language" : "eng",
         "language" : "en",
         "name" : "English (United States)"
      }
   ],
   "id": "en-US",
   "select" : "(**)",
   "start" : 0,
   "total" : 1
}

Get Custom Site Preferences

For the specified site and instance, read the custom preferences in the preference group. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.

Url

GET https://hostname:port/dw/data/v19_10/sites/{site_id}/site_preferences/preference_groups/{group_id}/{instance_type}?mask_passwords={Boolean}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

SitePreferences

Path Parameters

Parameter Type Description Constraints
group_id String The ID of the preference group.  
instance_type String One of {staging,development,sandbox,production,current}.  
site_id String The site context. minLength=1

Query Parameters

Parameter Type Description Constraints
mask_passwords Boolean Set to true to mask the values of preferences of type Password.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomPreferenceGroupNotFoundException

preferenceGroupId (String)

Indicates the preference group is not found.

Sample

REQUEST:
GET /s/-/dw/data/v19_10/sites/SiteGenesis/site_preferences/preference_groups/my-preferencegroup/staging?expand=sites HTTP/1.1
Host: example.com
Authorization: Bearer aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8

{
   "_v" : "19.10",
   "_type" : "preferences",
   "link" : "https://example.com/s/-/dw/data/v19_10/sites/SiteGenesis/site_preferences/preference_groups/my-preferencegroup/staging",
   "site" : 
   {
    "_type" : "site",
    "id" : "SiteGenesis",
    "in_deletion" : false,
    "link" : "https://example.com/s/-/dw/data/v19_10/sites/SiteGenesis",
    "storefront_status" : "online"
   },
   "c_preference1" : "Teal",
   "c_preference2" : 
   [
      "Small",
      "Large"
   ],
   "c_preference3" : false,
   "c_preference4" : 20
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.10",
  "fault":{
    "type":"CustomPreferenceGroupNotFoundException",
    "message":"No preference group with ID 'my-preferencegroup' was found."
  }
}

Update Custom Site Preferences

For the specified site and instance, update one or more custom preferences in the preference group. Preferences of type password cannot be set to "************" since it is a reserved value.

Url

PATCH https://hostname:port/dw/data/v19_10/sites/{site_id}/site_preferences/preference_groups/{group_id}/{instance_type}?mask_passwords={Boolean}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

SitePreferences

Response Document

SitePreferences

Path Parameters

Parameter Type Description Constraints
group_id String The ID of the preference group.  
instance_type String One of {staging,development,sandbox,production}.  
site_id String The site context. minLength=1

Query Parameters

Parameter Type Description Constraints
mask_passwords Boolean Set to true to mask the values of preferences of type Password.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomPreferenceGroupNotFoundException

preferenceGroupId (String)

Indicates the preference group is not found.
404 ObjectTypeNotFoundException

objectType (String)

Indicates the SitePreferences system object is not found.

Sample

REQUEST:
PATCH /s/-/dw/data/v19_10/sites/SiteGenesis/site_preferences/preference_groups/my-preferencegroup/staging HTTP/1.1
Host: example.com
Authorization: Bearer aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

{
   "c_preference1" : "Teal",
   "c_preference2" : 
   [
      "Small",
      "Large"
   ],
   "c_preference3" : false,
   "c_preference4" : 20
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8

{
   "_v" : "19.10",
   "_type" : "preferences",
   "link" : "https://example.com/s/-/dw/data/v19_10/sites/SiteGenesis/site_preferences/preference_groups/my-preferencegroup/staging",
   "site" : 
   {
    "_type" : "site",
    "id" : "SiteGenesis",
    "in_deletion" : false,
    "link" : "https://example.com/s/-/dw/data/v19_10/sites/SiteGenesis",
    "storefront_status" : "online"
   },
   "c_preference1" : "Teal",
   "c_preference2" : 
   [
      "Small",
      "Large"
   ],
   "c_preference3" : false,
   "c_preference4" : 20
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.10",
  "fault":{
    "type":"CustomPreferenceGroupNotFoundException",
    "message":"No preference group with ID 'my-preferencegroup' was found."
  }
}

Get Slot Configurations

Action to get all the slot configurations with no filtering.

Url

GET https://hostname:port/dw/data/v19_10/sites/{site_id}/slot_configurations?start={Integer}&count={Integer}&select={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

SlotConfigurations

Path Parameters

Parameter Type Description Constraints
site_id String The id of the site. minLength=1

Query Parameters

Parameter Type Description Constraints
count Integer Optional count for retrieving only a subset of the items (default is 25).  
select String The property selector.  
start Integer Optional start index for retrieving the items from a given index (default 0).  

Sample

REQUEST:
GET  /s/-/dw/data/v19_10/sites/SiteGenesis/slot_configurations?select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
{
  "_v" : "19.10",
  "count" : 2,
  "data" : [
    {
        "_v":"19.10",
       "_type" : "slot_configuration",
        "slot_id":"header-banner",
        "uuid":"fsdoi43ofijwdf",
        "configuration_id":"2015-06-24_16:33:18",
        "slot_content":
        {
            "type":"html",
            "body":
            {
                "default":"<html>HTML content</html>"
            }
        },
        "customer_groups":[
            "Administrators",
            "Registered"
        ],
        "assigned_to_site" : true,
        "context":"global",
        "enabled":true,
        "default":true,
        "rank":2,
        "description":"slot configuration description",
        "callout_msg":
        {
            "default":"some message"
        },
        "schedule":
        {
            "start_date":"2013-03-28T23:21:00.000Z",
            "end_date":"2022-03-28T23:21:00.000Z",
            "recurrence":
            {
                "day_of_week":[
                    "monday",
                    "sunday"
                ],
                "time_of_day":
                {
                    "time_from":"00:00:00",
                    "time_to":"23:59:00"
                }
            }
        }
    }
  ],
  "select": "**",
  "start" : 0,
  "total" : 1
}