XperienCentral GraphQL API

In This Topic

In XperienCentral R42, the new XperienCentral GraphQL API has been added. In future releases, this functionality will be expanded.

Features

The GraphQL API enables the consumer of the API to retrieve any publicly available content items from XperienCentral, either by querying directly by ID or retrieving a list of content items filtered by parameters.

Current Features

• Retrieval of XperienCentral's default MediaItemVersions and PageVersions based on its ID, including the most relevant fields. 
• Retrieval of a list of XperienCentral's default media item versions
• Retrieval of a list of XperienCentral's default page versions
• Filtering the results when retrieving a list of content item versions
• Sorting the results when retrieving a list of content item versions

Planned Features

• Support for Elements & Rich Text content
• Support for read access
• Support for Modular Content types
• Support for Modular Elements
• Support for Modular Page metadata
• Support for custom Modular Content fields

Enabling the GraphQL API

You can enable the GraphQL API in the General tab of the Setup Tool under the section graphqlservice(beta) by selecting the enable_api checkbox. The API is now available at the URL <server name>/web/delivery. You can access this URL using a POST request using one of the supported REST client applications (GET requests return no value). 

Authentication

It's possible to only allow specific users access to the GraphQL. This will require a valid User with an application key. You can enable authentication in the Setup by enabling the require_authentication option.

Executing Your First Request

Assuming that an article exists in XperienCentral with version id=1, you can execute the following GraphQL query to the API using your favorite REST client application, for example Insomnia or Postman.

query {
   mediaItemVersion(id:1) {
      contentType
   } 
}

which will return

{
   "data": {
      "mediaItemVersion": {
         "contentType": "article"
	  }
   }
}

Exploring the Documentation

The inline documentation of the API can be explored using one of the REST clients mentioned above. Using Insomnia, you can click the schema button and the select "Show documentation". This opens a popup containing the API's documentation.

Extending the API

XperienCentral's GraphQL implementation provides developers with extensive options to extend the API with custom requests, additional types and additional implementations. The GraphQL implementation of XperienCentral builds on top of the GraphQL SPQR library, which makes adding queries and fields to your API very simple. In addition to that XperienCentral provides several interfaces that can be used to extend the API with your own custom functionality.

Adding custom media items or elements to the API

In order to add support for custom, non modular, media item to the API XperienCentral provides an Interface that can be used to register these types to the API. This interface is called the AdditionalImplementationProvider (Matthew Wagner TODO: Add a link to the Javadoc for this interface when it's published) and can be found in the webmanager-api library. This interface only contains one method: 

    /**
     * Returns a list of classes that need to be parsed by the ConfigurationBuilder, The provided classes should
     * implement a default XperienCentral interface.
     *
     * @return a list of implementing classes
     */
    List<Class<?>> getImplementingClasses();

In order to actually register your custom implementation to the GraphQL API you will need to create a service component within your Media item plugin that implements this interface. The method should return a list of implementation classes for your media items. These implementation classes should be annotated with the @GraphQLType annotation and contain one or methods that have been annotated with @GraphQLQuery annotations from the GraphQL SPQR library. The code snippet below, taken from the Media Item based on the Media item archetype, shows how an example on how to do this.

@Interfaces("com.gxwebmanager.tests.testmediaitem.api.TestmediaitemMediaItemVersion")
@GraphQLType
public class TestmediaitemMediaItemVersionImpl extends MediaItemArticleVersionImpl implements TestmediaitemMediaItemVersion {
    /**
     * {@inheritDoc}
     */
    @Property
    @GraphQLQuery
    public Calendar getDate() {
        return JcrUtil.getCalendar(getPrivateNode(), WCBConstants.NAMESPACE_PREFIX + ":date");
    }
    ...
}

The service component should look like this

package com.gxwebmanager.tests.testmediaitem.service;

import nl.gx.webmanager.services.graphql.AdditionalImplementationProvider;
import nl.gx.webmanager.wcb.servicetype.impl.SimpleServiceComponent;

import java.util.List;

public class AdditionalImplementationProviderImpl extends SimpleServiceComponent implements AdditionalImplementationProvider {
    /**
     * Returns a list of classes that implement any GraphQL interface type
     *
     * @return a list of annotated classes that implement any GraphQL interface type
     */
    @Override
    public List<Class<?>> getImplementingClasses() {
        return List.of(TestmediaitemMediaItemVersionImpl.class);
    }
}

This results in the following GraphQLType in the schema.

type TestmediaitemMediaItemVersionImpl implements IMediaItemVersion {
  
  // Default media items fields here

  date: Calendar
}

 Please note that installing a plugin that implements the AdditionalImplementationProvider interface will trigger a Schema regeneration within the API.

Adding custom queries

It's also possible to add custom queries to the API to return your own data. This can be done using theGraphQLDeliveryApi.Provider interface which allows you to register your own queries to the GraphQL API. Again this can be done using a service component. Let start by creating a Service component, using the Quick Start guide. This will generate a plugin for you with a service component. This will provide you with the following files in the com.gxwebmanager.helloworld.helloworldservice folder.

• Activator.java
• api/
  • package.html
  • HelloWorldServiceService.java
  • WCBConstants.java
• service/
  • package.html
  • HelloWorldServiceServiceImpl.java

Now we're going to edit the Activator.java and the HelloWorldServiceServiceImpl.java. In order to be picked up by the GraphQL API the HelloWorldServiceServiceImpl.java needs to implement the GraphQLDeliveryApi.Provider interface. In addition any methods that should be exposed in the API need to be annotated using the GraphQL SPQR annotations. The file below contains a complete example if the file.

package com.gxwebmanager.helloworld.helloworldservice;

import com.gxwebmanager.helloworld.helloworldservice.api.HelloWorldServiceService;
import io.leangen.graphql.annotations.GraphQLQuery;
import nl.gx.webmanager.wcb.servicetype.impl.SimpleServiceComponent;

import io.leangen.graphql.annotations.GraphQLQuery;
import nl.gx.webmanager.wcbs.graphqlservice.api.GraphQLDeliveryApi;

import java.text.DateFormat;
import java.util.Date;

/**
 * Implementation of the HelloWorldService service component.
 */
public class HelloWorldServiceServiceImpl extends SimpleServiceComponent implements GraphQLDeliveryApi.Provider, HelloWorldServiceService {
    /**
     * {@inheritDoc}
     */
    @GraphQLQuery
    public String getTimeStamp() {
        return DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT).format(new Date());
    }
}

In addition the Activator also needs to be updated. The following line needs to be updated from:

definition.setInterfaceClassNames(new String[]{TestserviceService.class.getName()});

to

definition.setInterfaceClassNames(new String[]{TestserviceService.class.getName(),  GraphQLDeliveryApi.Provider.class.getName()});

Now build the plugin and deploy it on your environment. The getTimestamp query will be registered to the GraphQL API.