33 GraphQL endpoints

A database can answer GraphQL, with a schema generated from the datamodel. Each node type you expose becomes a GraphQL type with a field per property, and root fields that fetch a node by id or page through nodes with filters, text search and ordering. Relations become fields a query can follow, and mutations can be switched on. You write no resolvers. The schema follows the datamodel and the endpoint as they change.

{
  events(filter: { price: { gte: 200 } }, orderBy: starts, pageSize: 2) {
    totalCount
    items { id title starts price venue { name } }
  }
}

There are two ways to set up an endpoint.

In the admin UI, with no code. Open the database, choose API, then New endpoint. In the Types view, tick the node types to expose and give each a GraphQL name, such as Event for IEvent. Choose Save. The endpoint answers on /graphql at once, and the Try it view runs queries against it. See §33.1.

In code. Map a route in Program.cs that exposes the whole datamodel. See §33.9.

using Relatude.DB.GraphQL;
using Relatude.DB.NodeServer;

app.UseRelatudeDB();
app.MapRelatudeDBGraphQL("/graphql", o => {
    o.StoreResolver = _ => RelatudeDBRuntime.Database.Datastore;
    o.EnableExplorer = true;   // open /graphql in a browser to try it
});

Both are part of the Relatude.DB.Server package and need no third-party libraries.

One query per root field. Each root field runs as one store query (§19–§26), with its filter, search, ordering, paging and the relations the selection follows. A page of 25 events with their venues and hosts is one query, not 51. Values from the request go in as parameters, never as query text.

33.1 An endpoint in the admin UI — Open a database, choose API, then New endpoint. The new endpoint answers on /graphql, or /graphql2 and so on when that is taken, and starts with no types chosen. The editor has seven views:
33.2 The definition file — An endpoint is a JSON file, <name>.json, kept in one of two places like the other definitions the admin UI edits (§12.2): SHARED: relatude.settings/graphql/, or relatude.settings/<ShortName>/graphql/ for a database with…
33.3 The schema — Every exposed node type gets a GraphQL type and two root fields on Query: one that fetches a node by id, such as event(id: ID!); one that returns a page of nodes, such as events(filter, search, orderBy, descending, page…
33.4 Querying — A list root field returns a page: items, totalCount (the matches before paging), the pageIndex and pageSize used, and durationMs. Its arguments:
33.5 Views — A view is a root field defined by a query. It returns the same result type as the type's list field and takes the same arguments, so clients can still filter, search, order and page within it. The view's own query is…
33.6 Mutations — With allowMutations on, every exposed type that can be created gets three fields on Mutation:
33.7 Over HTTP — The status codes are: 200 when there is data, even if some fields failed; 400 when the request produced no data at all (syntax, validation, variables), or the body is not valid JSON; 401 when the API key is missing…
33.8 The explorer and the facet page — Two switches put a page on the endpoint's url, for a browser that opens it. With both on, the page has a tab for each, and ?explorer opens the explorer directly. The explorer (enableExplorer) builds, runs and documents…
33.9 Code-first: mapping an endpoint in Program.cs — MapRelatudeDBGraphQL maps one route that exposes the whole datamodel in GraphQL-style names, with its options set in code. An interface IEvent gives the root fields iEvent and iEvents (§33.3).
33.10 Who reads, and the limits — Who reads. Every query runs in a query context (§29), and an endpoint, its facet page included, shows only what that context can read. An endpoint made in the admin UI reads as an anonymous visitor…