Docs Developer Site
Project Guillotine - Headless API for Enonic XPUsage

Usage

Contents

This section describes how to access and use the API via Content Studio extension.

About GraphQL

GraphQL is a query language developed by Facebook. Compared to RESTful APIs, GraphQL is strongly typed and self-documented. It also enable client developers to request exactly the information required in as few requests as possible.

Learn more about GraphQL…​

Query playground

After installing Guillotine, a new menu item called Query playgroud will be automatically injected into the Content Studio menu. This is currently only accessible for users with system.admin or cms.admin roles.

Using the Query playground you may run queries against the contextual project content. You may choose to query either the draft items (draft branch), or the published items (master branch).

  • The left panel allows you to edit your GraphQL query

  • The center panel displays the result of the query execution

  • The right panel is used to display documentation generated from the GraphQL API.

  • The toolbar is extended by the dropdown for choosing the branch and the refresh button, which allows to re-generate a schema

  • Each query is executed in a specific context, which is determined by the repository and the branch

Query playground interface
Looking for the API endpoint? Visit the API endpoints section for details.

Queries

  • Paste the query below inside the left panel.

    This query can be read as: Retrieve the display name and type of the root items.

  • Click on the query play button above

  • The service response is displayed in the center panel

getSite 
{
  guillotine{
 		getChildren(key:"/") {
 		displayName
 		}
 	}
}

Subscriptions

Guillotine also enables you to use GraphQL subscription in order to listen to events from the server.

The subscriptions are implemented using Websockets, providing instant and high performance streaming of events over HTTP.

Listen to server events for the specific site 
subscription {
  event {
    type
    dataAsJson
  }
}

Just like for regular queries, Guillotine listens to events only for the contextual repository and branch

Content Interface

The type Content is an interface with multiple implementations from both built-in and custom defined content types. These types are dynamically generated based on your deployed schemas.

Types implementing Content share the same fields, with the exception of the data field, which offers a specific implementation per type.

Query content

The API lets you perform rich queries based on Enonic XP’s NoSQL storage. This includes ranked search, filters, stemming, aggregations and highlighting to mention a few things.

Query example: Simple query to fetch blog posts from the app "com.enonic.app.myapp". For each post, return its display name and the display name of the referenced author 
{
  guillotine {
    query(contentTypes:"com.enonic.app.myapp:post") {
      displayName
      ... on com_enonic_app_myapp_Post {
        data {
          author {
            displayName
          }
        }
      }
    }
  }
}

References

References between content items are available via regular fields, allowing you to traverse and extract content through graphs and structures.

By default, each items has the following common reference fields:

  • parent: the parent content item

  • children: the child item(s) if any

Schemas with ContentSelector, MediaSelector or ImageSelector will generate references to the target item(s).

Query example: Retrieve the display name of a specific content and the display name of its direct children 
{
  guillotine {
    get(key: "/path/to/item") {
      displayName
      children {
        displayName
      }
    }
  }
}

Images

Enonic XP can dynamically render images at runtime. Guillotine uses this functionality by calling the "imageUrl" function which will generate a URL for the desired image size and crop.

Example: Scaled Image URL - Retrieve the image contents and generate absolute URLs to these images cropped to 800x200px 
{
  guillotine {
    query(contentTypes:"media:image") {
      displayName
      ... on media_Image {
        imageUrl(scale:"block(800,200)",type:absolute)
      }
    }
  }
}

Rich text

Rich text fields provide configuration parameters that give you control over output from links, images and much more.

Example: Process HTML - Retrieve the blog posts. For each post, return its author display name, tags and processed content. 
{
  guillotine {
    query(contentTypes:"com.enonic.app.myapp:post") {
      ... on com_enonic_app_myapp_Post {
        data {
          author {
            displayName
          }
          tags
          post(processHtml:{type:absolute}) {
             processedHtml
          }
        }
      }
    }
  }
}

More details about Rich text processing.

Contents