Exploring GraphQL integration With BIGKit

GraphQL is a pretty exciting technology, certainly one that is gaining a lot of traction at the moment. What is exciting about it, is that complex layering of parameterized subqueries is possible, all whilst being grounded to a fully typed schema. It covers not only querying, but mutations — a way to update data, and even subscriptions. It is also language agnostic, so your consuming technology can be whatever you currently are most comfortable with, aided by an appropriate library.

I have had this on my radar for some time, being interested but not having any reason to use it in anger. A few weeks ago, however, the penny dropped. BIGKit already has a lot of the prerequisites required to create a dynamically generated GraphQL endpoint: it has a type system, a schema, an abstract DSL around the Table Query engine, multi-tenanted databases, import/export.

The only missing piece was creating the interface between our domain, and an appropriate library designed to do the heavy lifting of constructing these endpoints. Luckily, such a library exists already, so thanks again to the f# community for creating FSharp.Data.GraphQL, which forms the foundation of this endpoint.

By going to the Data tab, you can now access a new API/GraphQL area, allowing you to configure API key access. For exploring the API surface, we suggest checking grapiql-online (for public access), or if you are a chrome user and want to be able to use API keys: graphql playground. On initial endpoint configuration, it will attempt to retrieve the schema, which is then consumed and used to provide the language service with auto-completion options. You may also wish to configure what auth mechanisms can be used with the GraphQL API in the “Settings” tab. Currently, you can incrementally enable and disable public access, API key access, and OIDC access for schema, read, and write. More granular field-level control is already functional but still needs some refinement.

Querying

Each entity generates a queryable field, all of which can support optional parameters for id, skip and take along with a basic pass of the filter DSL. You can also already request deeply nested objects/lists/blob file references, along with entity time-travel, events, and foreign-keys.

Mutation

It is also possible to update an entity by id and any of its fields arbitrarily. As with all entity updates, events for field update deltas are automatically created in the background for auditing and reprojection purposes.

Because there is nothing like trying this out yourself, we have provided a dummy public access API with a trivial schema in our documentation project available at: https://app.leansquad.co.uk/api/b701d9b0-004b-4462-83f5-43aa86502b31/476347052/3/gql

A typed react client demo

I have also thrown together a demo repo to get started, which uses the fantastic graphql-zeus client generator, typescript, and react. You can clone it from here.

To point it at your endpoint, you simply need to replace the path of your client in the package.json scripts section with your endpoint and rerun the generate-gql-client script. Bear in mind that the schema/introspection query will need to be run, so depending on what kind of auth header is provided, permissions need to be set correctly in BIGKit settings.

In closing

Although this is still quite an early prototype, we are excited with the possibilities of allowing teams to integrate external applications. It is possible now to create a self-hosted SPA for fine-grained control and have it be entirely driven by our GraphQL backend. On top of this, hybrid approaches are also possible where data capture and management is handled by BIGKit and an external application then consumes the data, much like how a modern headless CMS works, with the fundamental difference that we do not have a publishing mechanism for individual entities. On the flip side though, we do have environments, so if there is a demand for this we could explore creating more granular ways of pushing data between these environments.

We would love your feedback on where we go with this. Some ideas that are on the radar:

• Enhance filter DSL
• More integration with entity events
• Integration with Indexes (denormalised reprojections in elastic search)
• Triggers and custom queries — being able to define custom GraphQL mutation constructs with business logic using our Action system, thus potentially allowing typescript.
• GraphQL Scope in BIGKit application itself, allowing consumption of this and perhaps other external graphql api’s

As always, we welcome you to check out our samples, create a free account with us and get started today.