---
title: "Reference Data Client API"
slug: "reference-data-client-api"
abstract: "Overview of the Reference Data Client API with examples."
---
# Reference Data Client API

The Reference Data Client API accesses the Reference Data Service over HTTPS. It is represented by the `ReferenceDataHttpClient` class, and implements the `IReferenceDataClient` interface.

> [!note]
> Synchronous and asynchronous versions of each method are available. For example, `EnsureDefinitionType()` and `EnsureDefinitionTypeAsync()`.

All examples use a basic `Definition<string,string>` defintion type, but you can also create [custom types](https://doc.sitecore.com/xp/en/developers/93/sitecore-experience-platform/create-custom-reference-data-types.html "Create custom reference data types").

<details>
<summary><h2>Get the Reference Data Client API in a Sitecore context</h2></summary>

The following example demonstrates how to retrieve a read-only and a read/write instance of the Reference Data Client API in a Sitecore context:

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
namespace Documentation
{
    public class RefDataClients
    {
        public async void AsyncExample()
        {
            // Read-write client
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            // Read-only client
            var readOnlyClient = ServiceLocator.ServiceProvider.GetService(typeof(IReadOnlyReferenceDataClient)) as IReadOnlyReferenceDataClient;
        }
    }
}

```

> [!note]
> In a Sitecore context, configuration controls whether the service implementation or the HTTP client implementation is returned.

</details>

<details>
<summary><h2>Get the Reference Data Client API in a non-Sitecore context</h2></summary>

The following example demonstrates how to construct the `ReferenceDataHttpClient` in a non-Sitecore context:

```csharp
using System;
using Microsoft.Extensions.Logging;
using Sitecore.Xdb.Common.Web;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core.Converter;

namespace TestConsoleApp
{
    public class RefDataHttpClientNonSitecore
    {
        public async void AsyncExample()
        {
            var url = "https://refdata/";

            var converter = new DefinitionEnvelopeJsonConverter();

            // Valid certificate thumbprints must be passed in
            var options = CertificateHttpClientHandlerModifierOptions.Parse(
"StoreName=My;StoreLocation=LocalMachine;FindType=FindByThumbprint;FindValue=BC6DBAC6D7E7796E5816DBA268FE2B7036F0F8D9");

            // Optional timeout modifier
            IHttpClientHandlerModifier[] handlers = { new CertificateHttpClientHandlerModifier(options) };

            var logger = new Logger<ReferenceDataHttpClient>(new LoggerFactory());

            var client = new ReferenceDataHttpClient(
                converter,
                new Uri(url),
                handlers,
                logger
             );
         }
     }
 }

```

</details>

<details>
<summary><h2>Retrieve a definition</h2></summary>

The following example demonstrates how to retrieve a definition. If you do not specify a culture, all available cultures are returned.

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;

namespace Documentation
{
    public class RefDataGetDefinition
    {
        public async void AsyncExample()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
            var criteria = new DefinitionCriteria("voyager", definitionType);

            var definition = await client.GetDefinitionAsync<string, string>(criteria, false);

            var definitionData = definition.CultureData[new CultureInfo("en-us")]; // Get language from e.g. Sitecore.Context.CurrentLanguage.CultureInfo
        }
    }
}

```

### Retrieve a culture-specific definition

The following example demonstrates how to retrieve a culture-specific definition:

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;

namespace Documentation
{
    public class RefDataGetDefinitionCulture
    {
        public async void AsyncExample()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            // Retrieve Latest Active Definition with Danish Culture Only
            var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
            var criteria = new DefinitionCriteria("voyager", definitionType)
            {
                Culture = new CultureInfo("da") // Get language from e.g. Sitecore.Context.CurrentLanguage.CultureInfo
            };

            var definition = await client.GetDefinitionAsync<string, string>(criteria, false);

            // Get Danish culture
            var data = definition.CultureData[new CultureInfo("da")]; // Get language from e.g.Sitecore.Context.CurrentLanguage.CultureInfo
        }
    }
}

```

### Retrieve culture-invariant definition

The following example demonstrates how to retrieve a culture invariant definition:

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;

public class RefDataGetDefinitionCultureInvariant
{
    public async void AsyncExample()
    {
        var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

        // Retrieve Latest Active Definition Culture Invariant
        var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
        var criteria = new DefinitionCriteria("voyager", definitionType)
        {
            Culture = CultureInfo.InvariantCulture
        };

        var definition = await client.GetDefinitionAsync<string, string>(criteria, false);

        var data = definition.CultureData[CultureInfo.InvariantCulture];
    }
}

```

Culture invariant data is used when data has a culture, but that culture is not explicitly defined by the source of the data. For example, an external provider might provide a list of city names in English, but does not explicitly specify the culture of the data. In such cases, data should be stored as culture invariant.

</details>

<details>
<summary><h2>Save a Definition</h2></summary>

The following example demonstrates how to create and save a new definition in various cultures:

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;

namespace Documentation
{
    public class RefDataSaveDefinition
    {
        public async void Example()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            var definitionType = await client.EnsureDefinitionTypeAsync("country");

            var definitionKey = new DefinitionKey("se", definitionType, 1);
            var definition = new Definition<string, string>(definitionKey)
            {
                IsActive = true,
                                    CommonData = "the common data",
                                    CultureData = {
                                            { new CultureInfo("en"), "Sweden" }
                                    }
            };

            // aDd another definition culture
            definition.CultureData[new CultureInfo("se")] = "Sverige";

            // Culture invariant data (has culture, but culture is unknown)
            definition.CultureData[CultureInfo.InvariantCulture] = "Swedenland";

            await client.SaveAsync(definition);
        }
    }
}

```

</details>

<details>
<summary><h2>Save Multiple Definitions</h2></summary>

The following example demonstrates how to save multiple definitions:

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;
using Sitecore.Xdb.ReferenceData.Core.Collections;

namespace Documentation
{
    public class RefDataSaveDefinition
    {
        public async void Example()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            var definitionType = await client.EnsureDefinitionTypeAsync("country");

            var definitionKey = new DefinitionKey("se", definitionType, 1);
            var definition = new Definition<string, string>(definitionKey)
            {
                IsActive = true
            };

            definition.CultureData[new CultureInfo("en")] = "Sweden";
            definition.CultureData[new CultureInfo("se")] = "Sverige";

            var definitionKey2 = new DefinitionKey("de", definitionType, 1);
            var definition2 = new Definition<string, string>(definitionKey)
            {
                IsActive = true
            };

            definition.CultureData[new CultureInfo("en")] = "Germany";
            definition.CultureData[new CultureInfo("se")] = "Tyskland";

            var definitions = new DefinitionCollection<string, string>
            {
                definition,
                definition2
            };

            await client.SaveAsync(definitions);
        }
    }
}

```

</details>

<details>
<summary><h2>Activate a Definition</h2></summary>

To activate a definition, set the `IsActive` property of the definition to `true` and save the definition.

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;

namespace Documentation
{
    public class RefDataActivateDefinition
    {
        public async void AsyncExample()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
            var criteria = new DefinitionCriteria("voyager", definitionType);

            var definition = await client.GetDefinitionAsync<string, string>(criteria, false);

            definition.IsActive = true;

            await client.SaveAsync(definition);
        }
    }
}

```

</details>

<details>
<summary><h2>Get all definitions by a specific type</h2></summary>

The following example demonstrates how to get all definitions by a specific type and paginate the results.

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
namespace Documentation
{
    public class RefDataActivateGetByType
    {
        public async void AsyncExample()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");

            // Gets the first 10 active definitions
            var definitions = await client.GetDefinitionsByTypeAsync<string, string>(definitionType, true, 1, 10);

            var pageOneDefinitions = definitions.Definitions;
            var currentPage = definitions.PageNumber;
            var currentPageSize = definitions.PageSize;
            var totalDefinitions = definitions.Total; // Total number of definitions with type 'starfleet ships'
        }
    }
}

```

</details>