Add GraphQL & AI subpage (/ai) with interactive demos - #2469
Conversation
New /ai route showcasing GraphQL for AI systems (MCP servers, RAG, agents & tool calling). Includes hero with canvas particle network, interactive Star Wars GraphQL demo executing real queries client-side, syntax-highlighted code blocks, by-the-numbers stats, and CTA. - src/app/(main)/ai/: page + 9 components (hero, interactive-demo, how-it-works, why-graphql-ai, use-cases, by-the-numbers, cta-community, syntax-highlight) - src/pages/_meta.tsx: add 'ai' nav entry pointing to /ai - src/globals.css: add @Keyframes fadeInUp used by interactive demo - package.json + pnpm-lock.yaml: add sharp dependency
|
@aexol is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel. A member of the Team first needs to authorize it. |
Run `prettier --write` on the 7 files flagged by `pnpm format:check` to unblock the CI prettier check on the feat/ai-subpage branch. No behavioral changes — formatting only.
| rest: "ad-hoc", | ||
| restDesc: "no guarantees", | ||
| explanation: | ||
| "GraphQL responses match the query shape exactly — validated against the schema at runtime. REST responses offer no structural guarantees, forcing LLMs to handle arbitrary JSON shapes.", |
There was a problem hiding this comment.
This is somewhat disingenuous considering that OpenAPI exists, and that most programming languages are fully typed.
I would suggest that this breaks down for agents specifically when they need to remember very complex types with deep relationships.
It's not the types that make the difference. It's that you don't need to know all of them at the same time when dealing with graph data.
| rest: "manual", | ||
| restDesc: "per endpoint", | ||
| explanation: | ||
| "Every GraphQL API includes built-in introspection. Agents can discover available types, fields, and arguments automatically. REST tool calling requires hand-crafted JSON Schema definitions for every endpoint.", |
There was a problem hiding this comment.
It doesn't have to be hand-crafted. Nearly every REST framework has automatic OpenAPI auto-creation capability built-in, so I don't think this is a point in GraphQL's favor.
You have to tell the agent where that schema is produced. It's built-in to the spec in GraphQL, so GraphQL is plug-in-play.
Similarly - and not mentioned here - is how easy it is to add per-field, per class, and per query documentation which can also be introspected.
So you need only a graphql schema instead of needing an AGENT.md + RAML + API in order to have things work with AI, and you don't need to tell an agent how to get to all three things; you only need one thing.
Type safety: REST is also typed (OpenAPI), so claiming 'no structural guarantees' was disingenuous. Both now show 100%; the real GraphQL edge for agents is graph traversal — no need to hold the entire type graph in context at once. Tool definitions: REST frameworks auto-generate OpenAPI, so 'hand-crafted' was inaccurate. The genuine advantage is plug-and-play: introspection and per-field/per-type/per-query docs are built into the spec and discoverable from one endpoint. With REST an agent needs the API + schema + an instruction file (AGENT.md), and you must point it to each. One GraphQL schema replaces all three (REST now shows '3' files to wire).
| graphQLDesc: "typed responses", | ||
| rest: "ad-hoc", | ||
| restDesc: "no guarantees", | ||
| rest: "100%", |
There was a problem hiding this comment.
Maybe you shouldn't make it 100% considering the statement?
There was a problem hiding this comment.
ok let me think more about this one
| restDesc: "files to wire", | ||
| explanation: | ||
| "Every GraphQL API includes built-in introspection. Agents can discover available types, fields, and arguments automatically. REST tool calling requires hand-crafted JSON Schema definitions for every endpoint.", | ||
| "REST frameworks can auto-generate OpenAPI, so this isn't about hand-writing schemas. The edge is plug-and-play: GraphQL's introspection and per-field, per-type, and per-query documentation are built into the spec and discoverable from one endpoint. With REST, an agent needs the API, its schema, and an instruction file (AGENT.md) — and you must point it to each. One GraphQL schema replaces all three.", |
There was a problem hiding this comment.
If you're including this in the description, it might be a good idea to also include examples of comment documentation embedded into a schema and queryable.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
number overflowing (safari) 
|
|
I think we should omit these input boxes given I cannot type anything to avoid confusion |
|
You have a very nice hero this looks off so we should remove it 
|
|
I wonder if we should darken the overlay on the pink lines, or use the same dark lines we have on other pages. The buttons are very invisible on the page so having something darker in background would help with contrast. 
|
…layout - Add 'Docs live in the schema' subsection under the stats with three side-by-side code panes: a schema with embedded """ descriptions, the built-in __type introspection query, and the response returning those docs — proving documentation is queryable, not a separate file. Verified against the real graphql package (introspection returns the embedded descriptions). - Rebuild the GraphQL vs REST comparison from heavy stateful StatCards (IntersectionObserver count-up, 96px numbers, gradient bars, per-card callouts) into a compact, stateless table (Metric | GraphQL | REST | Why). Drop unused React hooks and ArrowUpIcon imports. - Make the comparison responsive: stacked compact panels on mobile (md:hidden) where the 4-column table was unusably tall (1868px), full table on desktop (hidden md:block). Reduces mobile section height by ~1360px. - Address reviewer feedback: REST is also typed, so Type safety now shows 'if used with correct tooling' instead of 'via OpenAPI'; Tool definitions already reframed around plug-and-play introspection vs wiring API + schema + AGENT.md. - Tighten section padding (lg:py-16 xl:py-24 -> lg:py-12 xl:py-16) and docs subsection gap (mt-16 -> mt-10).
| @@ -0,0 +1,297 @@ | |||
| "use client" | |||
There was a problem hiding this comment.
hey, the codebase already includes a GraphQL syntax highlighter used on other pages
should this really be added? maybe zero dependency isn't really a worthwhile goal to pursue if the design consistency is lost code grows with multiple solutions for one problem?
@aexol wdyt about using the mask image blur blobs the other pages used to make the stripes fade out and keep text readable |
|
@saihaj made changes to number section in the last commit |
|
@saihaj and I will take your design suggestions into account |
6 participants
New /ai route showcasing GraphQL for AI systems (MCP servers, RAG, agents & tool calling). Includes hero with canvas particle network, interactive Star Wars GraphQL demo executing real queries client-side, syntax-highlighted code blocks, by-the-numbers stats, and CTA.
Closes #
Description