GraphQL API to store and manage structured data with Git
npm install @commitspark/graphql-apiCommitspark is a set of tools to manage structured data with Git through a GraphQL API.
This library provides the GraphQL API that allows reading and writing structured data (entries) from and to a Git
repository.
Queries and mutations offered by the API are determined by a standard GraphQL type definition file (schema) inside the
Git repository.
Entries (data) are stored using plain YAML text files in the same Git repository. No other data store is needed.
There are two common ways to use this library:
1. By making GraphQL calls directly to the library as a code dependency in your own JavaScript / TypeScript /
Node.js application.
To do this, simply install the library with
``shell`
npm i @commitspark/graphql-api
2. By making GraphQL calls over HTTP to this library wrapped in a webserver or Lambda function of choice.
Please see the Node.js Express server example
or Lambda function example for details.
This library is agnostic to where a Git repository is stored and relies on separate adapters for repository access. To
access a Git repository, use one of the pre-built adapters listed below or build your own using the interfaces
in this repository.
| Adapter | Description | Install with |
|---------------------------------------------------------------------|------------------------------------------------------------|---------------------------------------------|
| GitHub | Provides support for Git repositories hosted on github.com | npm i @commitspark/git-adapter-github |npm i @commitspark/git-adapter-gitlab
| GitLab (SaaS) | Provides support for Git repositories hosted on gitlab.com | |npm i @commitspark/git-adapter-filesystem
| Filesystem | Provides read-only access to files on the filesystem level | |
Commitspark builds a GraphQL data management API with create, read, update, and delete (CRUD) functionality that is
solely driven by data types you define in a standard GraphQL schema file in your Git repository.
Commitspark achieves this by extending the types in your schema file at runtime with queries, mutations, and additional
helper types.
Let's assume you want to manage information about rocket flights and have already defined the following simple GraphQL
schema in your Git repository:
`graphqlcommitspark/schema/schema.graphql
directive @Entry on OBJECT
type RocketFlight @Entry {
id: ID!
vehicleName: String!
payloads: [Payload!]
}
type Payload {
weight: Int!
}
`
At runtime, when sending a GraphQL request to Commitspark, these are the queries, mutations, and helper types that are
added by Commitspark to your schema for the duration of request execution:
`graphql
schema {
query: Query
mutation: Mutation
}
type Query {
everyRocketFlight: [RocketFlight!]
RocketFlight(id: ID!): RocketFlight
_typeName(id: ID!): String
}
type Mutation {
createRocketFlight(id: ID!, data: RocketFlightInput!, commitMessage: String): RocketFlight
updateRocketFlight(id: ID!, data: RocketFlightInput!, commitMessage: String): RocketFlight
deleteRocketFlight(id: ID!, commitMessage: String): ID
}
input RocketFlightInput {
vehicleName: String!
payloads: [PayloadInput!]
}
input PayloadInput {
weight: Int!
}
`
Let's now assume your repository is located on GitHub and you want to query for a single rocket flight.
The code to do so could look like this:
`typescript
import { createAdapter } from '@commitspark/git-adapter-github'
import { createClient } from '@commitspark/graphql-api'
const gitHubAdapter = createAdapter({
repositoryOwner: process.env.GITHUB_REPOSITORY_OWNER,
repositoryName: process.env.GITHUB_REPOSITORY_NAME,
accessToken: process.env.GITHUB_ACCESS_TOKEN,
})
const client = await createClient(gitHubAdapter)
const response = await client.postGraphQL(
process.env.GIT_BRANCH ?? 'main',
{
query: query ($rocketFlightId: ID!) {
rocketFlight: RocketFlight(id: $rocketFlightId) {
vehicleName
payloads {
weight
}
}
},
variables: {
rocketFlightId: 'VA256',
}
},
)
const rocketFlight = response.data.rocketFlight
// ...
`
#### postGraphQL()
This function is used to make GraphQL requests.
Request execution is handled by ApolloServer behind the scenes.
Argument request expects a conventional GraphQL query and supports query variables as well as introspection.
#### getSchema()
This function allows retrieving the GraphQL schema extended by Commitspark as a string.
Compared to schema data obtained through GraphQL introspection, the schema returned by this function also includes
directive declarations and annotations, allowing for development of additional tools that require this information.
As Commitspark is Git-based, all GraphQL requests support traversing the Git commit tree by setting the ref argument
in library calls to a
* ref (i.e. commit hash),
* branch name, or
* tag name (light or regular)
This enables great flexibility, e.g. to use branches in order to enable data (entry) development workflows, to retrieve
a specific (historic) commit where it is guaranteed that entries are immutable, or to retrieve entries by tag such as
one that marks the latest reviewed and approved version in a repository.
Mutation operations work on branch names only and (when successful) each append a new commit on
HEAD in the given branch.
To guarantee deterministic results, mutations in calls with multiple mutations are processed sequentially (see
the official GraphQL documentation for details).
The data model (i.e. schema) is defined in a single GraphQL type definition text file using the
GraphQL type system.
The schema file must be located at commitspark/schema/schema.graphql inside the Git repository (unless otherwise
configured in your Git adapter).
Commitspark currently supports the following GraphQL types:
* type
*
*
To denote which data is to be given a unique identity for referencing, Commitspark expects type annotation with
directive @Entry:
`graphql
directive @Entry on OBJECT # Important: You must declare this for your schema to be valid
type MyType @Entry {
id: ID! # Important: Any type annotated with @Entry must have such a field`
# ...
}
Note: As a general guideline, you should only apply @Entry to data types that meet one of the following
conditions:
* You want to independently create and query instances of this type
* You want to reference or link to an instance of such a type from multiple other entries
This keeps the number of entries low and performance up.
Entries, i.e. instances of data types annotated with @Entry, are stored as .yaml YAML text files insidecommitspark/entries/
folder in the given Git repository (unless otherwise configured in your Git adapter).
The filename (excluding file extension) constitutes the entry ID.
Entry files have the following structure:
`yaml`
metadata:
type: MyType # name of type as defined in your schema
referencedBy: [ ] # array of entry IDs that hold a reference to this entry
data: ... fields of the type as defined in your schema
#### References
References to types annotated with @Entry are serialized using a sub-field id.
For example, consider this variation of our rocket flight schema above:
`graphql
type RocketFlight @Entry {
id: ID!
operator: Operator
}
type Operator @Entry {
id: ID!
fullName: String!
}
`
An entry YAML file for a RocketFlight with ID VA256 referencing an Operator with ID Arianespace will look
like this:
`yaml`commitspark/entries/VA256.yaml
metadata:
type: RocketFlight
referencedBy: [ ]
data:
operator:
id: Arianespace
The YAML file of referenced Operator with ID Arianespace will then look like this:
`yaml`commitspark/entries/Arianespace.yaml
metadata:
type: Operator
referencedBy:
- VA256
data:
fullName: Arianespace SA
When this data is deserialized, Commitspark transparently resolves references to other @Entry instances, allowing for
retrieval of complex, linked data in a single query such as this one:
`graphql`
query {
RocketFlight(id: "VA256") {
id
operator {
fullName
}
}
}
This returns the following data:
`json`
{
"id": "VA256",
"operator": {
"fullName": "Arianespace SA"
}
}
#### Unions
Consider this example of a schema for storing content for a marketing website built out of modular content elements,
where field contentElements is an array of Union type ContentElement, allowing different concrete types Hero orText to be applied:
`graphql
type Page @Entry {
id: ID!
contentElements: [ContentElement!]
}
union ContentElement =
| Hero
| Text
type Hero {
heroText: String!
}
type Text {
bodyText: String!
}
`
During serialization, concrete type instances are represented through an additional nested level of data, using the
concrete instance's type name as field name:
`yaml`
metadata:
type: Page
referencedBy: [ ]
data:
contentElements:
- Hero:
heroText: "..."
- Text:
bodyText: "..."
When querying data through the API, this additional level of nesting is transparently removed and not visible.
Instead of throwing errors, this library catches known error cases and returns error information for GraphQL calls via
the errors response field. The type of error is indicated in error field extensions.code, with additionalextensions.commitspark
information in error field (where available). This allows API callers to determine the cause of
errors and take appropriate action.
Example GraphQL response with error:
`json`
{
"errors": [
{
"message": "No entry with ID \"SOME_UNKNOWN_ID\" exists.",
"extensions": {
"code": "NOT_FOUND",
"commitspark": {
"argumentName": "id",
"argumentValue": "SOME_UNKNOWN_ID"
}
}
}
]
}
The following error codes are returned together with error codes of Git adapters as
documented here:
| Error code | Description |
|------------------------|-------------------------------------------------------------------|
| BAD_USER_INPUT | Invalid input data provided by the caller |NOT_FOUND
| | Requested resource (entry, type, etc.) does not exist |BAD_REPOSITORY_DATA
| | Data in the repository is malformed or invalid |SCHEMA_DATA_MISMATCH
| | Data in the repository does not match the schema definition |BAD_SCHEMA
| | Schema definition is malformed or invalid |IN_USE
| | Entry cannot be deleted because it is referenced by other entries |INTERNAL_ERROR` | Internal processing error |
|
The code in this repository is licensed under the permissive ISC license (see LICENSE).