GlobalPreferences resource (Data API 19.1)

Summary

Http Method Resource Description
GET /global_preferences/preference_groups/{group_id}/{instance_type} For the specified instance, read the custom preferences in the preference group at the global(organization) level.
PATCH /global_preferences/preference_groups/{group_id}/{instance_type} For the specified instance, update one or more custom preferences in the preference group at the global(organization) level.

Get Custom Preferences

For the specified instance, read the custom preferences in the preference group at the global(organization) level.

Url

GET https://hostname:port/dw/data/v19_1/global_preferences/preference_groups/{group_id}/{instance_type}?mask_passwords={Boolean}&expand={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

OrganizationPreferences

Path Parameters

Parameter Type Description Constraints
group_id String The ID of the preference group.  
instance_type String An instance type, one of {staging,development,sandbox,production}.  

Query Parameters

Parameter Type Description Constraints
expand String The expansion "sites" retrieves the custom preferences in the preference group for all the available sites.  
mask_passwords Boolean The preference values of type Password are masked when set.  

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_1/global_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.1",
   "_type" : "organization_preferences",
   "link" : "https://example.com/s/-/dw/data/v19_1/global_preferences/preference_groups/my-preferencegroup/staging",
   "site_preferences" : 
   [
      
      {
         "_type" : "preferences",
         "link" : "https://example.com/s/-/dw/data/v19_1/sites/Site1/site_preferences/preference_groups/my-preferencegroup/staging",
         "site" : 
         {
            "_type" : "site",
            "id" : "Site1",
            "in_deletion" : false,
            "link" : "https://example.com/s/-/dw/data/v19_1/sites/Site1",
            "storefront_status" : "online"
         },
         "c_preference1" : "Blue",
   		 "c_preference2" : 
   		 [
      		"Small",
      		"Medium"
   		 ],
   		 "c_preference3" : true,
   		 "c_preference4" : 11
      },
	  {
         "_type" : "preferences",
         "link" : "https://example.com/s/-/dw/data/v19_1/sites/Site2/site_preferences/preference_groups/my-preferencegroup/staging",
         "site" : 
         {
            "_type" : "site",
            "id" : "Site1",
            "in_deletion" : false,
            "link" : "https://example.com/s/-/dw/data/v19_1/sites/Site1",
            "storefront_status" : "online"
         },
         "c_preference1" : "Green"
      }
   ],
   "c_preference1" : "Red",
   "c_preference2" : 
   [
      "Small",
      "Large"
   ],
   "c_preference3" : true,
   "c_preference4" : 10
}

# 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.1",
  "fault":{
    "type":"CustomPreferenceGroupNotFoundException",
    "message":"No preference group with ID 'my-preferencegroup' was found."
  }
}

Update Custom Preferences

For the specified instance, update one or more custom preferences in the preference group at the global(organization) level.

Url

PATCH https://hostname:port/dw/data/v19_1/global_preferences/preference_groups/{group_id}/{instance_type}?mask_passwords={Boolean}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

OrganizationPreferences

Response Document

OrganizationPreferences

Path Parameters

Parameter Type Description Constraints
group_id String The ID of the preference group.  
instance_type String An instance type, one of {staging,development,sandbox,production}.  

Query Parameters

Parameter Type Description Constraints
mask_passwords Boolean The preference values of type Password are masked when set.  

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:
PATCH /s/-/dw/data/v19_1/global_preferences/preference_groups/my-preferencegroup/staging HTTP/1.1
Host: example.com
Authorization: Bearer aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

{
   "c_preference1" : "Red",
   "c_preference2" : 
   [
      "Small",
      "Large"
   ],
   "c_preference3" : true,
   "c_preference4" : 10
}

# 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.1",
   "_type" : "organization_preferences",
   "link" : "https://example.com/s/-/dw/data/v19_1/global_preferences/preference_groups/my-preferencegroup/staging",
   "c_preference1" : "Red",
   "c_preference2" : 
   [
      "Small",
      "Large"
   ],
   "c_preference3" : true,
   "c_preference4" : 10
}

# 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.1",
  "fault":{
    "type":"CustomPreferenceGroupNotFoundException",
    "message":"No preference group with ID 'my-preferencegroup' was found."
  }
}