How to use the CoreMedia Headless Service with GraphQL

Learn how to use the CoreMedia Headless Service and execute a first GraphQL query. For the installation you need a running CoreMedia 9 system and the current Headless Contribution at GitHub.

Install the Workspace

For our local development environment we need the same tools as for the CoreMedia 9 Workspace: Java, Maven, GIT and Docker. We can run the service without Docker, but with Docker it’s much easier. A CoreMedia Content Server, to which the Headless Service connects, should be available locally or remotely. Once we’ve checked out the Headless Contribution at GitHub, we can build the headless service. If you get a 404 error, you will need a GitHub account and activation by CoreMedia support.

> git clone git@github.com:coremedia-contributions/coremedia-headless-server-app.git
> cd coremedia-headless-server-app
> mvn clean install
...
[INFO] Successfully built coremedia/caas-server:1.0
[INFO] -----------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] coremedia-headless-server-app ... SUCCESS [  1.815 s]
[INFO] preview-client .................. SUCCESS [  5.004 s]
[INFO] headless-server-app ............. SUCCESS [  5.863 s]
[INFO] headless-server-app-docker .......SUCCESS [ 10.344 s]
[INFO] -----------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] -----------------------------------------------------
>

In the directory headless-server-app-docker we find a shell script to start the Docker Container. Using the environment variables CONTENT_SERVER_HOST and CONTENT_SERVER_PORT we can configure the connection to our CoreMedia Server. The Docker Container has the name caas-server. CAAS means for Content as a Service. A look at the container logfile tells us if the headless server is running and has a connection to the CoreMedia Server.

> export CONTENT_SERVER_HOST=content-management-server
> export CONTENT_SERVER_PORT=40180
> sh headless-server-app-docker/docker-run-server.sh
...
CaaS Server for 'content-management-server' running on http://localhost:8080/.
> docker logs caas-server
...
Tomcat started on port(s): 8080 (http) with context path ''
Started CaasServletInitializer in 14.291 seconds (JVM running for 15.574)
Initializing Spring DispatcherServlet 'dispatcherServlet'
Initializing Servlet 'dispatcherServlet'
Completed initialization in 23 ms

Query Content with GraphQL

Our headless service is now ready. The Contribution provides two tools that make it easy even for GraphQL newbies to create their first query:

GraphiQL is a simple IDE for GraphQL. It runs directly in the browser and offers some cool features like Autocomplete, Prettify, Syntaxcheck and History.

http://localhost:8080/graphiql

For our first GraphQL query, we now need the content ID of an article document. We search for a suitable article in the CoreMedia Studio and determine the Content ID from the system tab.

The GraphQL query for this article document will look like this:

query ArticleQuery {
  content {
    article(id: "1496") {
      title
      teaserTitle
      teaserText
      picture {
        name
        creationDate
        alt
        uriTemplate
      }
    }
  }
}

As a result we receive a JSON document:

{
  "data": {
    "content": {
      "article": {
        "title": "Chef Corp.'s Mission",
        "teaserTitle": "Chef Corp.'s Mission",
        "teaserText": "<div><p>Since 1999, Chef Corp. is committed to deliver expert solutions with the personal attention you deserve.</p></div>",
        "picture": {
          "name": "About Us Picture",
          "creationDate": "2019-07-01T22:18:04Z[GMT]",
          "alt": "Symbolic picture for About Chef Corp. section with a variety of employees",
          "uriTemplate": "/caas/v1/media/2182/data/8d1575d685076c85a3f2a532a1b9ffbb/{cropName}/{width}"
        }
      }
    }
CoreMedia Headless GraphiQL IDE

This completes the first query. More information about GraphQL can be found here.

Query Media Objects by REST

What is pretty nice about the CAAS service is that linked documents and images can be embedded with their URLs. We can access the image with the following URL.

{cropName} = portrait_ratio1x1
{width} = 150 

http://localhost:8080/caas/v1/media/2182/data/1234567890/portrait_ratio1x1/115

We can also look at the API for Media Object with the Swagger UI.

http://localhost:8080/swagger-ui.html
CoreMedia Headless Swagger UI

Conclusion

This tutorial showed how to install the CoreMedia Headless Service and execute a simple query with GraphQL.