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 a short name. Commit it and deploy it with the application.
THIS SERVER: overrides/graphql/ on the database's storage, which is relatude.data/overrides/graphql/ by default. The API page saves here, and an endpoint here replaces the SHARED one with the same id.

Move to shared on the API page moves endpoints into SHARED. Every .json file in either folder is an endpoint, so you can also write one by hand and choose Reload from disk. Comments and trailing commas are allowed, and enum values are written by name.

{
  "name": "Public API",
  "description": "Events and venues for the web site.",
  "url": "/api/graphql",
  "mode": "Selected",
  "allowMutations": false,
  "enableExplorer": true,
  "enableFacetSearch": true,
  "apiKeys": [
    { "name": "Web site", "key": "6f1c…", "expires": "2027-10-07T00:00:00Z" },
    { "name": "Mobile app", "key": "a93e…" }
  ],
  "defaultPageSize": 25,
  "maxPageSize": 200,
  "types": [
    {
      "nodeTypeId": "0c7f9a52-1e4b-4f0a-9a7e-3d1c2b5e8f61", // IEvent
      "name": "Event",
      "properties": [
        { "propertyId": "5a1d3c7e-2b9f-4e61-8c0d-7f3e1a2b4c59" },                    // Title
        { "propertyId": "9e2b4d61-7c3a-4f58-b1e0-2d6f8a9c3e17", "name": "starts" },  // StartsUtc
        { "propertyId": "3c8e1f27-6d4b-4a90-9e5c-1b7d2f4a6e83" },                    // Price
        { "propertyId": "7b4f2e91-3a6c-4d18-8f2b-5e9c1d3a7b46" },                    // Status
        { "propertyId": "1f6a8c34-9b2e-4c57-a3d1-6e4b7f9c2a08" }                     // Venue
      ]
    },
    {
      "nodeTypeId": "4d2e6b81-8f3a-4c19-b7e2-9a5c3d1f6e24", // IVenue
      "name": "Venue",
      "readOnly": true,
      "properties": null
    }
  ],
  "views": [
    { "name": "upcoming", "query": "IEvent.Where(e => e.Status == 1)", "description": "Published events." }
  ]
}

Types and properties are referenced by their datamodel ids, so renaming a property in the model does not break the endpoint, except that a field without a name of its own follows the rename. The Types view fills in the ids, so start a file there.

Field	Default	What it does
`id`	from the file name	Identifies the endpoint.
`name`, `description`		Shown in the admin UI, the explorer and the generated code. The file is named after `name`.
`url`	`/graphql`	The path the endpoint answers on. Case and a trailing slash do not matter.
`enabled`	`true`	When `false`, the url is not answered and requests pass on to the application.
`mode`	`Selected`	`Selected` exposes what `types` lists. `WholeDatamodel` exposes every node type and property, and follows the datamodel as it changes.
`exactNames`	`false`	Use the datamodel's names as they are, not GraphQL-style names (§33.3).
`allowMutations`	`false`	Adds create, update and delete fields (§33.6).
`enableIntrospection`	`true`	Serves the schema: `__schema`, `__type`, `?sdl` and the explorer's data. Queries work either way.
`enableGetRequests`	`true`	Accepts `GET ?query=` requests. POST is always accepted.
`enableExplorer`	`false`	Serves the explorer page on the url (§33.8).
`enableFacetSearch`	`false`	Serves the facet search and its pivot page on the url (§33.8).
`maxFacetCards`	200,000	The most nodes the facet page draws.
`defaultNodeTypeId`	none	The type the explorer and the facet page open on.
`includeSystemTypes`	`false`	Whole-datamodel mode only: also expose the built-in users, groups, collections and cultures.
`apiKeys[]`	none	With any keys, every request needs one that has not expired (§33.7). Each has a `name`, the `key` and `expires`, in UTC.
`maxQueryDepth`	16	How deeply a selection may nest, fragments included.
`maxIncludeDepth`	8	How many relations deep a selection may follow.
`defaultPageSize`, `maxPageSize`	25, 200	The page size when a query gives none, and the largest allowed. A larger `pageSize` is cut down, not refused.
`types[]`		Selected mode only. Each entry has `nodeTypeId`, and optionally `name` (the GraphQL type name), `singleName` and `listName` (the root field names), `readOnly` and `properties`.
`views[]`		Each view has `name`, `query` and `description` (§33.5).

In types[], "properties": null exposes every property of the type, and a list exposes only the properties it names, each with a propertyId and an optional field name. In apiKeys[], leave out expires for a key that never expires.