Ulabase

Build

GraphQL applications

Give your app a GraphQL endpoint over your collections with no resolver code: you write a schema and say which collection answers each query.

GraphQL is a query language for APIs: the app asks for exactly the fields it needs, in one request. On Ulabase a GraphQL app is a schema and a mapping. The schema says which types and queries your app can ask for; the mapping says which collection answers each one.

Use it when your frontend speaks GraphQL, and each screen should get exactly the data it shows: an order with its customer, for example, in one request.

What you get:

  • No resolver code. Save the app under GraphQL and the endpoint is live at /graphql/<uri>.

  • Related data in one request. A field can look up a document in another collection, declared in one line of the mapping.

  • Several apps per service. Each app has its own schema and address.

The GraphQL page: the apps of the service

An app in one document

{
  "descriptor": { "name": "Shop", "description": "The shop's read API", "enabled": true, "uri": "shop" },
  "schema": "type Query { orders(status: String): [Order] } type Order { _id: String status: String total: Float customer: User } type User { _id: String name: String }",
  "mappings": {
    "Query": {
      "orders": { "db": "020009", "collection": "orders", "find": { "status": { "$arg": "status" } } }
    },
    "Order": {
      "customer": { "db": "020009", "collection": "users", "find": { "_id": { "$fk": "customerId" } } }
    }
  }
}
  • descriptor: the name, the uri the endpoint is served at, and enabled, which takes the app offline without deleting it.

  • schema: the GraphQL SDL, as a string. Types, queries, and mutations if you want them.

  • mappings: for each type, how each field is resolved. A root field names a db and a collection and optionally find, sort, limit and skip. $arg puts a query argument into the filter, so orders(status: "pending") becomes find({status: "pending"}). $fk takes a value from the parent document, which is how Order.customer looks up the user: a join, declared in one line.

On Free, Starter and Pro the database is the service’s own, named by its id: write the id, here 020009, and if you write another name the service sets it back to its own and says so in the response. On Enterprise, name the database you use.

Create one

Click New app. The Visual editor gives you a field for each part. The JSON editor takes the whole document, for one you paste from git. Both check what you type, and Format tidies the JSON. Save, and the endpoint answers. Changes take effect at once.

Each app in the list has an enable switch, Edit, Delete, and a copy icon for the endpoint address.

Call it from your app

const res = await fetch('https://c0ffee.ulabase.app/graphql/shop', {
  method: 'POST',
  headers: { 'Authorization': 'Basic ' + btoa('alice:secret'), 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'query Orders($status: String) { orders(status: $status) { _id total customer { name } } }',
    variables: { status: 'pending' }
  })
});
const { data } = await res.json();

The user needs a permission on /graphql/shop. Any GraphQL client works: paste the endpoint address into it.

From a script

Apps are documents in the gql-apps collection, /restheart/gql-apps on Enterprise:

Operation API

List

GET /gql-apps

Create

POST /gql-apps with the app document

Update

PATCH /gql-apps/<id>

Delete

DELETE /gql-apps/<id>

Query

POST /graphql/<uri>

Do it from the command line

You can keep a GraphQL app in git and apply it with ulabase setup. The app is the JSON document shown above, saved in a file. The step writes it to /gql-apps/<id>:

import { readFileSync } from 'node:fs';
import { defineSetup, step, isApiError } from '@ulabase/cli';

const id = 'shop';
// the app, read from a JSON file in the repository
const app = JSON.parse(readFileSync('graphql/shop.json', 'utf8'));

export default defineSetup('GraphQL', [
  step('shop app stored', {
    async check({ service }) {
      try {
        // the app is up to date when its schema and mappings match the file
        const stored = await (await service.fetch(`/gql-apps/${id}`)).json();
        return stored.schema === app.schema
            && JSON.stringify(stored.mappings) === JSON.stringify(app.mappings);
      } catch (e) {
        // 404: the app does not exist yet, so the apply creates it
        if (isApiError(e) && e.status === 404) return false;
        throw e;
      }
    },
    apply: ({ service }) =>
      // ?wm=upsert creates the app on the first run and replaces it on later runs
      service.fetch(`/gql-apps/${id}?wm=upsert`, { method: 'PUT', body: JSON.stringify(app) }),
  }),
]);

The id can use lower-case letters, digits, - and _. The first run creates the app, and later runs replace it with the file.