10. REST Access to GraphQL

Although CoreMedia recommends using the GraphQL endpoint to develop modern client applications, it may be desirable to run a client application using a REST API, for different reasons:

While the latter two objectives could be addressed by persisted queries, a query allow list and other security means (see Section 3.5, “Security”), the first objective is the most common one why you would want to add a REST layer on top of GraphQL.

The REST access to persisted queries is enabled by default. If REST access is not desired, the feature can be disabled by adding its autoconfiguration class to SpringBoots exclude list, e.g. in an environment variable.

SPRING_AUTOCONFIGURE_EXCLUDE=com.coremedia.caas.web.rest.RestMappingAutoConfiguration

The REST mapping of persisted queries allows for issuing REST requests instead of GraphQL queries. A list of REST endpoints can be configured which map the request to a corresponding Chapter 9, Persisted Queries. Moreover, the query result can optionally be transformed using JSLT in order to meet the client requirements.

All REST endpoints and their corresponding persisted queries are listed and visualized in the Swagger-UI.

CoreMedia delivers the following examples of persisted queries with the Headless Server:

The response of persisted queries using the GraphQL endpoint is JSON as specified by graphql.org. However, it is possible to invoke a JSLT transformation on the result transparently when using the REST endpoint to a persisted query. The files specifying the JSLT transformation must have the same name as the persisted query ID for which they are intended for. These files are stored in the folder resources/transformations. In addition to that, it is possible to define a default or fallback transformation by creating a file called default.jslt (see next Section 10.2, “JSLT Transformation” for details).

The corresponding REST endpoints to the example persisted queries are:

Figure 10.1. Headless server request/response flow using REST