Skip to main content

The REST API reference for the xDB Cloud service

Abstract

Customize your Sitecore xDB Cloud experience with this REST API reference.

Use this REST API reference to customize your Sitecore xDB Cloud solution.

Important

To ensure that your customers only access their own xDB sets, you must use a valid authentication token whenever you make a call to the xDB Cloud API. You can generate these tokens by using a valid Sitecore license file to call the SSO Encode Sitecore License endpoint. You must include the generated token as a HTTP header in all other requests called X-ScS-Nexus-Auth.

The xDB Cloud service consists of the following endpoints:

Get connection strings

Important

This endpoint only works for xDB Cloud 2.0.

Endpoint

https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/connectionstrings/{licenseId}/{deploymentId}

HTTP method

GET

Authentication

(custom header)

X-ScS-Nexus-Auth: {Nexus key}

Description

An endpoint that gets the connection strings for the xDB set.

Parameters

  • licenseId – Your Sitecore license ID

  • deploymentId – The unique identification of the deployment

Sample request

GET http://gateway-xdb-scs.cloud.sitecore.net/api/xdb/connectionstrings/<yourlicenseId>/<yourdeploymentId>

Sample JSON response

{
  "LicenseId": "<license id>",
  "DeploymentId": "<your deployment id>",
  "DeploymentType": "Prod",
  "SitecoreVersion": "Sitecore.NET 8.1 (rev. 160519)",
  "ReportingServiceUri": "https://Reporting-Prod-...-ne-Xdb-Sc.cloudapp.net",
  "ReportingServiceCertificate": "<certificate thumbprint>",
  "Indexes": {
    "sitecore-analytics-cloud-index": {
      "Name": "<index id>-analyticsindex",
      "BaseUrl": "https://<service id>.search.windows.net/indexes",
      "QueryKey": "<service key>",
      "ApiVersion": "2015-02-28"
    }
  },
  "XdbConnectionStrings": {
    "analytics": "mongodb://sc:<>.fleet.mongolab.com:46408/analytics...",
    "tracking.contact": "mongodb://sc:.fleet.mongolab.com/TrackingContact?...",
    "tracking.history": "mongodb://sc:fleet.mongolab.com/TrackingHistory?...",
    "tracking.live": "mongodb://sc:fleet.mongolab.com/TrackingLive?..."
  },
  "CloudSearchConnectionString": "serviceUrl=https://***.search.windows.net;apiVersion=2015-02-28-preview;apiKey=<api key>",
  "XdbCloudVersion": "2.0"
}

Get Firewall settings

Endpoint

https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/firewallsettings/{licenseId}/{deploymentId}

HTTP method

GET

Authentication

(custom header)

X-ScS-Nexus-Auth: {Nexus key}

Description

An endpoint that gets the firewall settings for the xDB.

Parameters

  • licenseId – Your Sitecore license ID

  • deploymentId – The unique identification of the deployment

Sample request

GET http://gateway-xdb-scs.cloud.sitecore.net/api/xdb/firewallsettings/yourlicenseId/yourdeploymentId

Sample JSON response

{
  "portRange": [
    "80",
    "443",
    "46408",
    "46406"
  ],
  "hostNames": [
    "*.sitecore.net",
    "dsxxxxx-a0.qmt44.fleet.mongolab.com",
    "dsyyyyy-a1.qmt44.fleet.mongolab.com"
  ]
}

Get Firewall settings V2

Endpoint

https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/firewallsettings/{licenseId}/{deploymentId}?v=2

HTTP method

GET

Authentication

(custom header)

X-ScS-Nexus-Auth: {Nexus key}

Description

An endpoint that gets the firewall settings for the xDB.

Parameters

  • licenseId – Your Sitecore license ID

  • deploymentId – The unique identification of the deployment

Sample request

GET http://gateway-xdb-scs.cloud.sitecore.net/api/xdb/firewallsettings/<yourlicenseId>/<yourdeploymentId>?v=2

Sample JSON response

{
    "SearchService":"https:// ***.search.windows.net:443",
    "ReportingService":"https://reporting-prod-***.cloudapp.net:443",
    "MongoDbPrimary":"ds***-a0.qmt44.fleet.mongolab.com:52829",
    "MongoDbSecondary":"ds***-a1.qmt44.fleet.mongolab.com:52829"
    "MongoDbArbiter":"ds***-ar0.qmt44.fleet.mongolab.com:52829"
}

Get history processing status

Endpoint

https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/historyProcessing/{licenseId}/{deploymentId}

HTTP method

GET

Authentication

(custom header)

X-ScS-Nexus-Auth: {Nexus key}

Description

An endpoint that gets the history processing status.

Parameters

  • licenseId – Your Sitecore license ID

  • deploymentId – The unique identification of the deployment

Sample request

GET https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/historyProcessing/xxxxxx/yyyy HTTP/1.1
X-ScS-Nexus-Auth:SDRzSUFBQUFBQUFFQU...

Sample JSON response

Possible responses are:

  • Done

  • In process

  • Error

  • None

Status code

200

Get version information

Endpoint

https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/version/{licenseId}/{deploymentId}

HTTP method

GET

Authentication

(custom header)

X-ScS-Nexus-Auth: {Nexus key}

Description

An endpoint that gets the version information of the xDB set.

Parameters

  • licenseId – Your Sitecore license ID

  • deploymentId – The unique identification of the deployment

Sample request

GET http://gateway-xdb-scs.cloud.sitecore.net/api/xdb/version/yourlicenseId/yourdeploymentId

Sample JSON response

{
"SitecoreVersion":"Sitecore.NET 8.1 (rev. 160519)",
"XdbCloudVersion":"2.0",
"DeploymentType":"Prod"
}

Get xDB collection verification dataset

Endpoint

https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/collection/{licenseId}/{deploymentId}

HTTP method

GET

Authentication

(custom header)

X-ScS-Nexus-Auth: {Your Nexus key}

Description

An endpoint that gets the xDB collection from the xDB set so that it can be verified.

Parameters

  • licenseId – Your Sitecore license ID

  • deploymentId – The unique identification of the deployment

Sample request

GET http://gateway-xdb-scs.cloud.sitecore.net/api/xdb/Collection/yourlicenseId/yourdeploymentId

Sample JSON response

{
  "DeploymentId": " mockdeployId",
  "Interactions": [],
  "Contacts": [
    {
      "Id": "e34a9403-95b7-4bf6-b964-ae7a98b525d5",
      "System": "QA.Demo",
      "Lease": "LeaseOne",
      "BehaviorProfiles": null,
      "Identifiers": "QA.One.Identifiers",
      "Personal": null,
      "Emails": null,
      "Successor": null,
      "Tags": null,
      "SocialProfile": null,
      "SocialKloutProfile": null
    },
    {
      "Id": "2db7c009-c524-4413-af66-5cb7c5c548bd",
      "System": "QA.Demo",
      "Lease": "LeaseOne",
      "BehaviorProfiles": null,
      "Identifiers": null,
      "Personal": null,
      "Emails": null,
      "Successor": null,
      "Tags": null,
      "SocialProfile": null,
      "SocialKloutProfile": null
    }
  ]
}

Get xDB consumption

Endpoint

https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/Consumption/{licenseId}/{deploymentId}/{year}/{month}

HTTP method

GET

Authentication

(custom header)

X-ScS-Nexus-Auth: {Your Nexus key}

Description

An endpoint that gets the xDB consumption and returns consumption for a specified period.

Parameters

  • licenseId – Your Sitecore license ID

  • deploymentId – The unique identification of the deployment

  • year – The consumption year

  • month – The consumption month

Sample request

GET https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/Consumption/44444444444444/MyXdbDeploymentId/2015/05 HTTP/1.1
X-ScS-Nexus-Auth:SDRzSUFBQUFBQUFFQU...

Sample JSON response

[
{"Consumption.Period":"2015-05-01T00:00:00",
"XdbSet.DeploymentId":"MyXdbDeploymentId",
"Storage.Size.InGB":23.3,
"Interactions.All.Count":1232.0,
"Interactions.Added":23.0,
"Contacts.All.Count"1230.0,
"Contacts.Identified.Count":54.0
},
{"Consumption.Period":"2015-05-02T00:00:00",
"XdbSet.DeploymentId":"MyXdbDeploymentId",
"Storage.Size.InGB":34.2,
"Interactions.All.Count":23432.0,
"Interactions.Added":3434.0,
"Contacts.All.Count":4342.0,
"Contacts.Identified.Count":34234.0}
]

Important

Use your Sitecore license ID, your deployment ID, and the relevant consumption year and consumption month for the endpoint. Also, use your Nexus key for authentication.

Get xDB set status

Endpoint

https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/{licenseId}/{deploymentId}/status

HTTP method

GET

Authentication

(custom header)

X-ScS-Nexus-Auth: {Your Nexus key}

Description

An endpoint that gets the status of the xDB set.

Parameters

  • licenseId – Your Sitecore license ID

  • deploymentId – The unique identification of the deployment

Sample request

GET https://gateway-xdb-scs-cloud.sitecore.net/api/xdb/xxxxxx/yyyy/status HTTP/1.1
X-ScS-Nexus-Auth:SDRzSUFBQUFBQUFFQU...

Sample JSON response

{"Status":"Ready","Message":null,"IssueIdOnError":null}

Status code

202

List xDB sets

Endpoint

https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/{licenseId}

HTTP method

GET

Authentication

(custom header)

X-ScS-Nexus-Auth: {Your Nexus key}

Description

An endpoint that gets the list of xDB sets and returns a list of xDB deployments.

Parameters

licenseId – Your Sitecore license ID

Sample request

GET https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/44444444444444 HTTP/1.1
X-ScS-Nexus-Auth:SDRzSUFBQUFBQUFFQU...

Sample JSON response

[
{"DeploymentId":"aaa”},
{"DeploymentId":"bbb"},
{"DeploymentId":"ccc"}
]

SSO Encode Sitecore license

Endpoint

https://gateway-sso-scs.cloud.sitecore.net/api/License/Encode

HTTP method

POST

Authentication

N/A

Description

An endpoint to get the encoded Nexus key.

Parameters

N/A

Header

Content-Type: application/xml

Body

Sitecore license file content (i.e. content of license.xml)

Sample request (body)

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="http://www.sitecore.net/licenseviewer/license.xsl"?>
<signedlicense id="yourlicenseId">
  ...  <Signature>    ...  </Signature>
  ... </signedlicense>

Trigger history processing (rebuild the Reporting database)

Endpoint

https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/historyProcessing/{licenseId}/{deploymentId}

HTTP method

PUT

Authentication

(custom header)

X-ScS-Nexus-Auth: {Your Nexus key}

Description

An endpoint that triggers the history process.

Parameters

  • licenseId – Your Sitecore license ID

  • deploymentId – The unique identification of the deployment

Header

Content-Type: application/json

Body

Note

You can only use the Request Body if you are running Sitecore 8.2-Update 6.

MinSaveDateTime - The date from when the data aggregation begins in the date format: 2000-01-01T00:00:00Z.

Targets - The targets parameter accepts two values:

  • ReportingDatabase - To rebuild the reporting database.

  • Index - To rebuild the Search index.

For example:

{

                "MinSaveDateTime"  : "2000-01-01T00:00:00Z",
                "Targets"  : "Index" 

}

Sample request (body)

{
 "MinSaveDateTime":"2018-01-03",
 "Targets":"ReportingDatabase"
}

Sample request

PUT https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/historyProcessing/xxxxxx/yyyy HTTP/1.1
X-ScS-Nexus-Auth:SDRzSUFBQUFBQUFFQU...

Status code

202

Cancel history processing (cancel 'rebuild the Reporting database')

Endpoint

https://gateway-xdb-scs.cloud.sitecore.net/api/xdb/cancel/historyProcessing/{licenseId}/{deploymentId}

HTTP method

PUT

Authentication (custom header)

X-ScS-Nexus-Auth: {Your Nexus key}

Description

An endpoint that cancels the history process.

Parameters

licenseId – Your Sitecore license ID

deploymentId – The unique identification of the deployment

Sample request

PUT http://gateway-xdb-scs.cloud.sitecore.net/api/xdb/cancel/historyProcessing /<yourlicenseId>/<yourdeploymentId>

Status code

202