Sites resource (Data API 22.4)

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}/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/v22_4/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/v22_4/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" : "22.4",
  "count" : 2,
  "data" : [ 
    {
        "_v" : "22.4",
        "_type" : "site",
        "customer_list_link" : {
            "_type" : "customer_list_link",
            "customer_list_id" : "SiteGenesis",
            "link" : "https://example.com/s/-/dw/data/v22_4/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/v22_4/sites/SiteGenesis",
        "storefront_status": "online"
    },
    {
        "_v" : "22.4",
        "_type" : "site",
        "customer_list_link" : {
            "_type" : "customer_list_link",
            "customer_list_id" : "MyCustomerList",
            "link" : "https://example.com/s/-/dw/data/v22_4/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/v22_4/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/v22_4/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/v22_4/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" : "22.4",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "site",
   "customer_list_link" : 
   {
      "_type" : "customer_list_link",
      "customer_list_id" : "SiteGenesis",
      "link" : "https://example.com/s/-/dw/data/v22_4/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" : "22.4",
   "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" : "22.4",
   "fault" : 
   {
      "type" : "SiteNotFoundException",
      "message" : "No site with ID 'foobar' was found."
   }
}

Get Locales

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

Url

GET https://hostname:port/dw/data/v22_4/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/v22_4/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" : "22.4",
   "_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/v22_4/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" : "22.4",
   "_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/v22_4/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" : "22.4",
   "_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/v22_4/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/v22_4/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" : "22.4",
   "_type" : "preferences",
   "link" : "https://example.com/s/-/dw/data/v22_4/sites/SiteGenesis/site_preferences/preference_groups/my-preferencegroup/staging",
   "site" : 
   {
    "_type" : "site",
    "id" : "SiteGenesis",
    "in_deletion" : false,
    "link" : "https://example.com/s/-/dw/data/v22_4/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" : "22.4",
  "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/v22_4/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/v22_4/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" : "22.4",
   "_type" : "preferences",
   "link" : "https://example.com/s/-/dw/data/v22_4/sites/SiteGenesis/site_preferences/preference_groups/my-preferencegroup/staging",
   "site" : 
   {
    "_type" : "site",
    "id" : "SiteGenesis",
    "in_deletion" : false,
    "link" : "https://example.com/s/-/dw/data/v22_4/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" : "22.4",
  "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/v22_4/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/v22_4/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" : "22.4",
  "count" : 2,
  "data" : [
    {
        "_v" : "22.4",
       "_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
}
X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.
X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.