NCP and GraphQL

GraphQL is a key technical enabler within the Nurocor Clinical Platform (NCP). In particular, GraphQL queries are an efficient and flexible way to retrieve NCP content. This blog entry is not intended to be a full GraphQL tutorial but rather to illustrate some important use cases of GraphQL as provisioned by NCP.

NCP microservices are “GraphQL first” in nature, exposing core Create/Read/Update/Delete (CRUD) actions on their business objects via GraphQL queries and mutations. GraphQL, originally developed by Facebook as part of its microservice-based platform architecture, provides two important features that make it especially well-suited for such development: federation and field (attribute) selectivity.

GraphQL Federation

Let’s first discuss federation. GraphQL supports the concept of API federation, where each microservice contributes its business object declarations to an all-encompassing graph spanning the entire set of business objects deployed into the platform. This federated view is exposed by a single GraphQL API endpoint. As each new microservice is deployed into the platform, it augments this object graph with the new objects for which it has responsibility. A GraphQL API consumer can in turn initiate a single API query that spans as much of the graph as is needed, with server-side infrastructure efficiently merging the content to support the API request.

All GraphQL content is represented as Types, with the Query Type serving as the root Type for data access. The Query Type lists the set of queries supported by the federated GraphQL API. In the case of NCP, a mix of configuration content standards queries (such as propertyGroupByNameVersion) and protocol and clinical study instance-specific (such as studies) queries are present. Configuration content (i.e., data standards) queries are provisioned into the federated NCP GraphQL API by Nurocor MDR, whereas instance-specific queries are provisioned by the Study Design and other NCP functional microservices. As you would expect, the studies query serves as the entry point to study and protocol content that is managed by the Study Design microservice. An API consumer can seamlessly navigate through the type hierarchy defined by Study Design, from StudyProtocol to StudyProtocolVersion to StudyDesign to Arm and so on. Each type in turn specifies its portion of the extensive set of attributes that NCP is managing to implement a Digitalized protocol.

Field Selectivity

Now let’s take a more detailed look at field selectivity. Field selectivity is a natural complement to business object federation, as GraphQL allows API consumers to precisely identify which object fields (attributes) are to be returned in query results. This eliminates the potential concern of very large datasets being returned to the client in response to a broad query invocation, while at the same time eliminating the need to implement multiple purpose-specific APIs supporting various combinations of object content to suit the needs of the client.

One of NCP’s key technical innovations is its ability to support dynamically configured applications. NCP establishes a nested Property Group/Property model within its MDR, where nested groups define dynamically generated applications/application pages/page sections, and page section groups in turn each contain a set of properties that represent the attributes to be presented within that page section. Every object-to-object relationship (i.e., edge) within this graph maintains application-specific context attributes that specify display aspects such as ordinality, read-only vs. editable, single vs. multi-value, and so on. The MDR implementation of GraphQL flattens page section context attributes with the associated property’s attributes into a consolidated representation that fully specifies how the UI is to present the attribute within the application currently in view. NCP applications require this full fidelity view over dynamic configuration content, whereas a reporting client may simply wish to retrieve the graph structure with name and ordinality attributes only in order to present a simplified graphical view of an application. Both objectives can be met by the single GraphQL API by simply specifying in the query request the desired attributes of interest.

Nurocor has been very pleased with the fit of GraphQL within NCP and is convinced that its power is essential to developing modern applications in support of clinical lifecycle digitization.