---
title: "Sitecore Layout Service"
slug: "sitecore-layout-service"
abstract: "Overview of the Sitecore Layout Service request and response models, the Layout Service Client configuration, and request operations."
---
# Sitecore Layout Service

> [!important]
> If you integrated your app before , it's using the legacy ASP.NET Core Rendering SDK, version 22 or earlier. This SDK is no longer receiving updates, so we recommend that you [upgrade to the latest version of the new](https://doc.sitecore.com/xmc/en/developers/asp-net/latest/asp-net-core-sdk/upgrade-from-v22.html) .

The [Sitecore Layout Service](https://doc.sitecore.com/xp/en/developers/hd/21/sitecore-headless-development/layout-service.html "Layout Service") is a [Sitecore Headless Services](https://doc.sitecore.com/xp/en/developers/hd/21/sitecore-headless-development/sitecore-headless-services.html "Sitecore Headless Services") endpoint that provides JSON formatted Sitecore content. You use the Sitecore Layout Service Client to communicate with the Layout Service, and you use the [Sitecore Rendering Engine](https://doc.sitecore.com/xp/en/developers/hd/21/sitecore-headless-development/asp-net-core-rendering-engine.html "ASP.NET Core Rendering Engine") to render the content.

The Layout Service Client libraries are available as NuGet packages, and their name is prefixed with `Sitecore.LayoutService.Client`.

<details>
<summary><h2>The SitecoreLayoutRequest model</h2></summary>

The `SitecoreLayoutRequest` model instantiates to an intermediate Data Transfer Object that supports the reading and writing of arbitrary properties. The Layout Service Client sends these properties to the Layout Service using query string keys.

The `SitecoreLayoutRequest` model includes a set of default properties with associated combined get/set methods. For example, `request.ApiKey()` gets the API Key value and `request.ApiKey("value")` sets the API Key value.

The default properties are:

| Property | Method | Content | Sample | Query string key |
| --- | --- | --- | --- | --- |
| API Key (required) | `ApiKey()` | [GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) | `123e4567-e89b-12d3-a456-426614174000` | `sc_apikey` |
| Item (required) | `Path()` | Content tree path | `/articles` | `item` |
| Site name | `SiteName()` | Human readable name | `MySite` | `sc_site` |
| Language | `Language()` | [ISO language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) | `en`, `en-GB`. | `sc_lang` |

</details>

<details>
<summary><h2>The SitecoreLayoutResponse model</h2></summary>

The Layout Service returns an object instantiated from the `SitecoreLayoutResponse` strongly typed model designed to allow navigation down to the field level. A `SitecoreLayoutResponse` object consists of several parts:

- `Request` - the `SitecoreLayoutRequest` sent to the Layout Service.
- `Metadata` - response metadata such as HTTP response headers.
- `Content` - the deserialized JSON response.
- `Errors` - the list of errors encountered while handling the `SitecoreLayoutRequest` object and building the `SitecoreLayoutResponse` object.
- `HasErrors` - this is true if the `Errors` list is not empty.

### Types and fields

`Content` uses the following types:

- `Route` - maps to the `Route` object in the JSON response returned by the Layout Service. Its fields are typed as a `Dictionary<string, IFieldReader>`.
- `Component` - maps to objects in the list value of a placeholder. Its fields are typed as a `Dictionary<string, IFieldReader>`.
- `IFieldReader` - maps to the field entries in a `Route` or `Component`. The implementation is provided by a serialization library such as Newtonsoft.
- `IField` - various implementations of `IField` are provided by the Layout Service Client. The interface is used as a marker to identify the types that can be read through an `IFieldReader`.

The Layout Service Client provides the following fields:

- `CheckboxField` - a checkbox field.
- `ContentListField` - a list of item link fields.
- `DateField` - a date and time field.
- `FileField` - a file field.
- `HyperLinkField` - a link field.
- `ImageField` - an image field.
- `ItemLinkField` - a single item field.
- `NumberField` - a number field.
- `RichTextField` - a rich text field.
- `TextField` - a single line or a multiline text field.

Fields can implement multiple interfaces to expose different field properties, such as:

- `IValueField<T>` - exposes a `Value` property of type `T`.
- `IEditableField` - exposes markup before and after editable fields.

### Syntax

The `IFieldReader` type exposes a `Read()` method that, when given a type that implements `IField`, returns an instance of the type populated with the data from the `IFieldReader`.

`Component` and `Route` both inherit the same base implementation that exposes `Fields`. In addition, they expose:

- `ReadField()` - receives a type of `IField` and a `string` to read a specified field.
-  `ReadFields()` - receives an arbitrary type that is populated with all the fields matching property names to field names.

</details>

<details>
<summary><h2>REST Layout Service Client configuration for ASP.NET</h2></summary>

The following example demonstrates the use of the Layout Service Client with the ASP.NET Rendering SDK in the `ConfigureServices` method of your application `Startup` class:

```csharp
services
  .AddRouting()
  .AddMvc()

  // Configure the required Newtonsoft.Json serialization behavior for use
  // with the Layout Service Client.
  // The Layout Service Client requires Json.NET due to limitations in System.Text.Json.
  .AddNewtonsoftJson(o => o.SerializerSettings.SetDefaults());

  // Register the Sitecore Layout Service Client,
  // which is used by the ASP.NET Rendering Engine.
  .AddSitecoreLayoutService()

  // Configure the default parameters for Layout Service Client requests.
  .WithDefaultRequestOptions(request =>
  {
    request

      // Optional language configuration, if the application is not using localized routes.
      // .Language("en")

      // The name of the Sitecore site that this application is rendering.
      .SiteName("website")

      .ApiKey("{00000000-0000-0000-0000-000000000000}");
  })

  // Provide the URL to the Layout Service on your Sitecore instance.
  // In production, this is typically a Content Delivery server.
  // In development, it might be a standalone combined Content Management
  // and Content Delivery instance.
  .AddHttpHandler("default", "https://<sitecore instance>/sitecore/api/layout/render/jss")
  .AsDefaultHandler();

```

To access the Layout Service, you must provide [the ID of the Sitecore Services Client API Key](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-manager/en/api-keys-for-the-odata-item-service.html) to the `ApiKey` method.

</details>

<details>
<summary><h2>GraphQL Layout Service Client configuration for ASP.NET</h2></summary>

The following example demonstrates how to configure a Layout Service client using a GraphQL endpoint:

```csharp
// The name of the Sitecore site the application is rendering.
  var siteName = "website";

  // The ID of the Sitecore Services Client API Key to access the GraphQl endpoint and Layout Service.
  var apiKey = "{00000000-0000-0000-0000-000000000000}";

  // The URL to the GraphQl Edge Scheme Endpoint on your Sitecore instance.
  // In production, this is typically an Experience Edge environment.
  // In development, it might be a standalone combined Content Management.

  var graphQlEndpoint = new Uri(
      "<https://<sitecore-or-edge-instance>>/<graphql-schema-url>"
  );

services 
  .AddRouting()
  .AddMvc()
  // Register the Sitecore Layout Service Client used by the ASP.NET Rendering Engine.
  .AddSitecoreLayoutService()
  .AddGraphQlHandler(
    handlerName: "default",
    siteName: siteName,
    apiKey: apiKey,
    endpoint: graphQlEndpoint)
  .AsDefaultHandler();

```

</details>