Context
The GraphQL endpoint (#66) is self-documenting via introspection, but without a visual interface, developers have to use curl or a separate Postman/Insomnia setup to explore the API. A GraphQL Playground served directly by Trident at /playground means a developer can paste the URL into a browser and immediately start writing queries — no setup required.
This is a high-leverage DX improvement that costs very little implementation effort but has an outsized impact on how quickly developers evaluate and adopt the API.
What needs to be built
Embedded static asset
The playground UI should be served from an embedded Go binary asset (using embed.FS) rather than loading from a CDN. This ensures the playground works:
- Fully offline (local dev, air-gapped environments)
- Without CORS configuration
- Without depending on a third-party CDN being reachable
Recommended library: GraphiQL 2 (MIT license, maintained by the GraphQL Foundation). The built distribution is a single index.html with inlined CSS and JS, approximately 500KB. Embed it as:
//go:embed graphiql/index.html
var graphiqlHTML embed.FS
Alternatively, Scalar API Reference (also MIT, lighter weight at ~200KB, more modern UI). Either is acceptable — document the choice in the PR.
Auto-configuration
The embedded HTML should have the GraphQL endpoint pre-configured to /graphql so developers do not have to type it in. If the playground HTML requires customization, template the endpoint URL using html/template to inject it from the server's known host.
The API key input should be pre-populated with an empty field and a clear label, not hard-coded.
Environment-gated access
The playground should be disabled in production to prevent exposing introspection to the public internet (introspection leaks your full schema, including field names that might reveal internal implementation details).
PLAYGROUND_ENABLED=true → serve /playground (dev/staging default)
PLAYGROUND_ENABLED=false → /playground returns 404 (prod default)
Default: false (secure by default). The Docker Compose dev file sets it to true automatically.
Route
GET /playground — returns Content-Type: text/html; charset=utf-8. No auth required (the playground itself will prompt for an API key in its UI when it makes requests to /graphql).
GET /playground/ (trailing slash) — 301 redirect to /playground.
Acceptance criteria
Dependencies
Context
The GraphQL endpoint (#66) is self-documenting via introspection, but without a visual interface, developers have to use curl or a separate Postman/Insomnia setup to explore the API. A GraphQL Playground served directly by Trident at
/playgroundmeans a developer can paste the URL into a browser and immediately start writing queries — no setup required.This is a high-leverage DX improvement that costs very little implementation effort but has an outsized impact on how quickly developers evaluate and adopt the API.
What needs to be built
Embedded static asset
The playground UI should be served from an embedded Go binary asset (using
embed.FS) rather than loading from a CDN. This ensures the playground works:Recommended library: GraphiQL 2 (MIT license, maintained by the GraphQL Foundation). The built distribution is a single
index.htmlwith inlined CSS and JS, approximately 500KB. Embed it as:Alternatively, Scalar API Reference (also MIT, lighter weight at ~200KB, more modern UI). Either is acceptable — document the choice in the PR.
Auto-configuration
The embedded HTML should have the GraphQL endpoint pre-configured to
/graphqlso developers do not have to type it in. If the playground HTML requires customization, template the endpoint URL usinghtml/templateto inject it from the server's known host.The API key input should be pre-populated with an empty field and a clear label, not hard-coded.
Environment-gated access
The playground should be disabled in production to prevent exposing introspection to the public internet (introspection leaks your full schema, including field names that might reveal internal implementation details).
Default:
false(secure by default). The Docker Compose dev file sets it totrueautomatically.Route
GET /playground— returnsContent-Type: text/html; charset=utf-8. No auth required (the playground itself will prompt for an API key in its UI when it makes requests to/graphql).GET /playground/(trailing slash) — 301 redirect to/playground.Acceptance criteria
GET /playgroundreturns 200 with a working GraphQL UI whenPLAYGROUND_ENABLED=trueGET /playgroundreturns 404 whenPLAYGROUND_ENABLED=false(or env var not set)/graphql— no manual endpoint entry requiredPLAYGROUND_ENABLEDdefaults tofalse(verified in the defaultdocker-compose.prod.yml){ events { edges { node { id } } } }query in the playground returns dataDependencies