Skip to main content

Reference Data Service API


Overview of the Reference Data Service API with examples.

The Reference Data Service API has direct access to the Reference Data Service database, and does not use the HTTP client.


Clients should use the Reference Data Client API. You cannot retrieve an instance of the Reference Data Service API in a Sitecore context.

The service API is used by callers from within the xDB, including:

  • The Reference Data Service.

  • The interaction aggregation pipeline, which runs on Standalone and Processing instances.

The Reference Data Client API is represented by the ReferenceDataService class, and implements the IReferenceDataClient interface, which means it can be used in exactly the same way as the Reference Data Client API.

The following example demonstrates how to construct an instance of the Reference Data Service API in a non-Sitecore context:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Logging;
using Sitecore.DependencyInjection;
using Sitecore.Framework.Conditions;
using Sitecore.Xdb.ReferenceData.Core.Converter;
using Sitecore.Xdb.ReferenceData.Service;
using Sitecore.Xdb.ReferenceData.Service.Cache;
using Sitecore.Xdb.ReferenceData.Service.Repository;
using Sitecore.Xdb.ReferenceData.SqlServer;
using Sitecore.Xdb.Sql.Common;
using System;

namespace Documentation
    public class RefDataClientsNonSitecore
        public async void AsyncExample()
            var retySettings = new RetryManagerSettings(5, TimeSpan.FromSeconds(3));
            var retryManager = new RetryManager(retySettings);
            var loggerFactory = new LoggerFactory();

            var refdataProviderLogger = new Logger<SqlServerReferenceDataProvider>(loggerFactory);

            // Expects xdb.referencedata to exist
            var refdataProvider = new SqlServerReferenceDataProvider("xdb.referencedata", refdataProviderLogger, retryManager);

            var refdataRepo = new ReferenceDataRepository(refdataProvider);
            var refdataCache = new NullDefinitionCache();

            var referenceDataServiceLogger = new Logger<ReferenceDataService>(loggerFactory);
            var refdataClient = new ReferenceDataService(refdataRepo, refdataCache, referenceDataServiceLogger, new DefinitionRecordJsonConverter());