Sitecore JSS with Next.js - Layout Service and the GraphQL Playground

In this article, I explain what the Layout Service is and how to use the GraphQL Playground in a Sitecore JSS with a Next.js solution.

Layout Service

The Sitecore Layout Service is a Sitecore Headless Services endpoint that exposes Sitecore layout information as structured JavaScript Object Notation (JSON) data.

The service leverages the Sitecore Rendering Engine to produce structured JSON output, decoupling layout and rendering, and allowing you to render Sitecore components with any front-end technology stack capable of consuming JSON data.

- Sitecore Documentation

The Sitecore Layout Service is used by the Sitecore rendering engine to pass the data to the components that we create in a JSS solution. We can query the layout service to find the data that is passed to the component.

The Sitecore Layout Service offers 2 APIs:

1. Get the whole layout of an item.
2. Get the layout for a particular placeholder.

To get the whole layout for an item, we use the render endpoint.

https://[site-url]/sitecore/api/layout/render/[config]?item=[path]&sc_lang=[language]&sc_apikey=[key]&sc_site=[your-site-name]

• [site-url] - The URL to your CM instance.
• [config] - The name of the Layout Service configuration. Usually, it is jss.
• [path] - The item path, or the relative path to the site if sc_site is passed.
• [language] - The language of the item, defaults to en if unspecified.
• [key] - The API key, can be found under the item path: /sitecore/system/Settings/Services/API Keys. The Item ID of the API Key item should be used.
• [your-site-name] - The name of your site.

For e.g., You can use the below query to get the layout for a page named demo.

https://cm.jssproject.localhost/sitecore/api/layout/render/jss?item=/sitecore/content/JSSProject/home/demo&sc_apikey={F51A1B4A-2898-4278-A7AA-F51FFCCB43BF}

If the same query is performed with the site context, it will be:

https://cm.jssproject.localhost/sitecore/api/layout/render/jss?sc_site=jssproject&item=/demo&sc_apikey={F51A1B4A-2898-4278-A7AA-F51FFCCB43BF}

To get the layout of a particular placeholder, we use the placeholder endpoint.

https://[site-url]/sitecore/api/layout/placeholder/[config]?placeholderName=/main&item=[path]&sc_lang=[language]&sc_apikey=[key]&tracking=[true|false]

The placeholder endpoint also aceepts the same parameters as the render endpoint, and the placeholder name, which is mandatory.

For e.g. You can use the below query to get the layout for the jss-main placeholder in the page named demo:

https://cm.jssproject.localhost/sitecore/api/layout/placeholder/jss?placeholderName=jss-main&sc_site=jssproject&item=/demo&sc_apikey={F51A1B4A-2898-4278-A7AA-F51FFCCB43BF}

GraphQL Playground

Sitecore also offers the Delivery API which is a GraphQL API to query for the layout.

This API can be accessed at the endpoint:

https://[site-url]/sitecore/api/graph/edge

The API Key has to be passed as a HTTP Header called sc_apikey and the query will be a graphql query.

Sitecore also offers a GUI IDE to query this API, which is called as the GraphQL Playgorund. The GraphQL Playgound can be accessed at the URL:

https://[site-url]/sitecore/api/graph/edge/ui

The API Key can be passed as a HTTP Header on the left bottom of your browser window in a JSON structure.

{ "sc_apikey": "{YOUR-API-KEY-HERE}" }

And the query can be written on the left side of the window. Once you click on the Execute Query button, the result of the query is fetched on the right side of the window.

Example Query:

# Write your query or mutation here
query {
  layout(site: "JSSProject", routePath: "/demo", language: "en") {
    item {
      rendered
    }
  }
}