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 queries, much like GraphiQL. It has:

• a schema tree to build a query by ticking fields, and documentation for every type and field;
• an editor with completion and validation, and results as JSON or as a table;
• the code to run a query in curl, PowerShell, JavaScript, TypeScript, C#, Python, Java and Go;
• a guide of runnable examples in the endpoint's own names.

It reads the schema through introspection, so it stays empty when introspection is off. The page loads without an API key and asks for one, which it keeps for the browser session. The admin UI's Explorer view is the same explorer, run against the draft.

The facet page (enableFacetSearch) is the admin UI's faceted search (§28) as a public page: a facet rail beside a visual pivot of the matching nodes. It uses only what the endpoint exposes, its types and facets on their exposed properties, and opens on defaultNodeTypeId or the first type. A facet on a relation or reference needs the target type exposed too. It differs from the admin UI's faceted search in three ways:

• it uses the datamodel's names, because the endpoint's renames apply only to its schema;
• it matches text by words only, since a semantic search would make a paid AI call per keystroke on a page anyone can open;
• it draws at most maxFacetCards nodes, the first ones of a larger result.

The page's requests go to ?facets=… on the same url, behind the same API key. The server answers them for endpoints made on the API page; a code-first endpoint needs FacetSearch (§33.9).