The REST API reference for the xDB Cloud service

Last updated Thursday, June 22, 2017 in xDB Cloud for Developer
Keywords: Cloud, Rules, xDB

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

{
"DeploymentId":"<your deployment id>",
"DeploymentType":"Prod",
"LicenseId":"<license id>",
"SitecoreVersion":"Sitecore.NET 8.1 (rev. 160519)",
"ReportingServiceUri":"https://Reporting-Prod-...-ne-Xdb-Sc.cloudapp.net",
"ReportingServiceCertificate":"<certificate thumbprint>",
"MongoDbConnectionStrings":
{
},
"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?..."
},
"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"
}

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

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

Send feedback about the documentation to docsite@sitecore.net.