- name
SKILL.md
Le fichier du skill reste dans le dépôt de l'éditeur.
Collez la commande copiée dans un terminal. Elle installe ce SKILL.md dans cet agent.
npx skills add samber/developer-platform-skills --skill public-graphql-api-design -a cursor -yCollez la commande copiée dans un terminal. Elle installe ce SKILL.md dans cet agent.
npx skills add samber/developer-platform-skills --skill public-graphql-api-design -a claude-code -yCollez la commande copiée dans un terminal. Elle installe ce SKILL.md dans cet agent.
npx skills add samber/developer-platform-skills --skill public-graphql-api-design -a codex -yCollez la commande copiée dans un terminal. Elle installe ce SKILL.md dans cet agent.
npx skills add samber/developer-platform-skills --skill public-graphql-api-design -a grok -yEnvoyez le message copié dans un chat Grok Bot. Le Bot récupère ce SKILL.md sur GitHub et l'ajoute aux skills que partagent tous vos Bots.
Install this skill: https://github.com/samber/developer-platform-skills/tree/HEAD/skills/public-graphql-api-designDe l'éditeur
You are a public GraphQL API designer. Design a GraphQL surface that third-party developers you have never met can query safely - schema conventions, pagination, typed errors, abuse ceilings, and the trust boundary - so the graph stays evolvable and the platform stays up.
Lee Byron (GraphQL co-creator) framed the problem GraphQL exists to solve: "You've got a square-peg, round-hole problem on the server and a round-peg, square-hole problem on the client." GraphQL earns its place when multiple client types genuinely need different shapes of the same data - that origin story, not a preference for graphs, is the test everything below starts from.
Memory (advised): When memory lives in a file, consider using developer-platform-context.md; if a different memory system is in use, rely on that instead. The file is an advisory reference, not a mandatory requirement. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.
Ask these before designing anything; each answer changes a later step. Batch them - this is a tactical design task, not a strategy interview.
If your harness has persistent memory, store the design's settled decisions so later runs (a new type, a schema review, the docs pass) start from the design instead of re-deriving it:
The split that changes the design is first-party vs third-party consumers:
Design for the third-party consumer whenever both are present; serve first-party traffic through the stricter policies it uniquely enables (step 7). A surface safe for unknown third parties serves your own apps for free; the reverse is false.
Each step has a section below, in order.
The default for a public API is REST, not GraphQL - the opposite of the internal-API instinct. Postman's survey data puts REST at over 80% of deployed public APIs versus roughly 28% of organizations using GraphQL anywhere. Re-ask the question even when the team arrives already committed; commitment by momentum is the failure this gate exists to catch.
REST wins by default for three concrete reasons:
GraphQL earns the investment when the consumer mix hits its genuine triggers:
No efficiency ranking here - this is a binary architecture gate against a trigger list, not a menu; ranking two paradigms by value-per-effort would be false precision when the answer hinges entirely on the consumer mix. The dominant production pattern is hybrid anyway: REST for the stable cacheable surface, GraphQL where the triggers hold - offering both is a legitimate outcome of this gate, not a failure to decide.
Two exit paths close this gate:
Set the conventions once, write them down, and lint against them - a public schema is read by strangers, so consistency of choice matters more than which choice.
is/has/can prefixes on booleans.publishPost, cancelOrder - never one monolithic updateOrder handling every field change. Two documented naming forks exist - Apollo's verb-first (createUser) and Shopify's noun-first (userCreate, chosen so a type's mutations group together alphabetically); ask the team which, then enforce it everywhere.input type and returns a dedicated payload type - never reuse an output type as an argument; the two have different nullability needs and different fields.[Type!]! for every list field (empty list over null list), non-null only where the domain genuinely guarantees a value. Mutation payload fields lean nullable so a partial failure can still return something (Shopify's Rule #24).Node interface (interface Node { id: ID! }) on every entity so any object is refetchable by one global, opaque ID. When a REST surface coexists, use one shared identifier across both - GitHub's node_id interop is the worked example (see References).author: User!, not authorId: ID! (Shopify's Rule #8) - the client fetches whatever depth it needs in one query instead of a second round trip.Viewer, UserProfile, and TeamMember may share name/email yet serve different use cases and evolve independently. Design types around client use cases, not around database tables."""docstrings""" for the public audience: a description naming an internal system leaks architecture to every schema reader.See references/schema-convention-tables.md for the full casing and nullability tables, the anti-pattern list, and worked SDL excerpts.
Every list a third party can grow must paginate, and the schema can't retrofit pagination onto a bare list field without a breaking change - decide per field now. Three shapes, ranked:
efficiency: Relay cursor connections > plain cursor list > offset arguments
effort: Relay cursor connections > plain cursor list > offset arguments
value: Relay cursor connections > plain cursor list > offset arguments
Default rung: Relay cursor connections (edges/node/cursor/pageInfo, first/after arguments). Highest effort and highest value - but client libraries and server frameworks implement the Relay spec natively, which collapses most of the effort in practice and is why it still wins the efficiency line. Cursors stay stable under concurrent writes and stay fast at any depth, which offset cannot do.
Step down to a plain cursor list (nodes plus endCursor, no edge wrapper) only when no per-edge metadata will ever exist and the team finds the connection boilerplate genuinely blocking - you keep cursor semantics and lose the spec-compatible tooling. GitHub's and Shopify's public GraphQL APIs both document this exact shape as a supported shortcut alongside full edges, so it is common practice with named public precedent, not an unwritten convention - but it is still a shortcut through the Relay spec's optional nodes field, not a competing standard.
Offset arguments (limit/offset) survive only for one niche: clients that genuinely need arbitrary page jumping over small, mostly static data. Under concurrent writes offset duplicates and skips items, and deep offsets force full scans - for a public API's default lists, this rung is a failure mode, not an option.
All three axes agree here, so this order starves nothing - the highest-effort rung is also the winner, because native framework support collapses its effort. It is still a default, not a law: re-rank against question 6.
Nothing here promotes offset for a public surface, but a hard deadline on an internal-first schema can justify the plain cursor rung as a stepping stone. Keep the field's return type a wrapper object from day one, so promoting it to a full connection later stays additive.
Whichever rung, cap page size server-side (first clamped to a documented maximum, e.g. 100) - the schema cannot express the bound, so enforce and document it. Connection page size is also the multiplier a cost budget prices lists by (step 5).
See references/relay-pagination-examples.md for the full connection SDL, cursor-design rules, the totalCount performance trap, and typed sort/filter arguments.
GraphQL gives you two genuinely different error mechanisms, and the design decision is which errors go where. Three postures, ranked:
efficiency: hybrid split > result types on every operation > built-in errors only
effort: result types on every operation > hybrid split > built-in errors only
value: result types on every operation == hybrid split > built-in errors only
Default rung: the hybrid split. Built-in top-level errors for what the caller can't plan around - server faults, malformed queries, authentication. Union or interface result types for every expected business outcome on mutations: union CreateOrderResult = CreateOrderSuccess | ValidationError | InsufficientInventory. The schema itself then documents every possible outcome, and a client cannot skip handling a failure mode the way it can with an untyped error body. Shopify's design tutorial reaches the same conclusion independently: built-in query-level errors are a poor fit for business-level mutation failure.
Promote to result types on every operation - queries included - when partial data is routine: fields backed by flaky upstreams each get their own result union (profileImage: ImageResult!). This is the starved rung: highest effort (every consumer needs ... on Type fragments everywhere) and it ties the value line only because expected failures on queries are rare in most schemas; routine partial data is the condition that promotes it anyway.
Built-in errors only is acceptable solely for a first-party-only surface where you control every client's error handling. On a third-party surface it is the anti-pattern: expected outcomes hidden in an untyped array, invisible to the schema.
Justify the value tie above per schema: if your queries do carry rich expected failures, the tie breaks upward and the promotion condition has fired. Re-rank against question 6 - a schema several teams will extend for years leans toward result types early, since adding a union to a shipped field is a breaking change.
Layer a shared ErrorCode enum under whichever posture wins, so clients switch on stable codes while message text stays free to change. The deep taxonomy discipline behind those codes is the error-design sibling's ground (see References).
See references/error-result-type-examples.md for full SDL of both patterns, the interface variant, batch/partial-success shapes, and the null-vs-error information-disclosure trap.
A public graph lets strangers compose queries of arbitrary shape; the guardrails are design decisions about what shape is ever acceptable, made before any scoring or metering exists. You own the ceilings; the cost-scoring mechanics that meter usage under them (point formulas, budgets per window, cost headers) belong to the rate-limit sibling (see References).
Federation is an internal composition architecture, not a public exposure mechanism. If the schema is federated, exactly one component is publicly reachable: the router. Every subgraph sits behind it, unreachable directly - treat any subgraph that answers requests from outside as a trust-boundary defect, not a deployment convenience.
Disabling introspection does not make a subgraph safe to expose, because federation's own coordination fields leak the same information and cannot be turned off without breaking composition:
Query._service { sdl } returns the subgraph's complete schema - a full introspection dump by another name.Query._entities resolves any @key-tagged entity by its key fields directly, bypassing the access-control logic in the subgraph's normal resolvers; its resolver is auto-generated and can't be selectively locked down.Apollo states the stakes plainly (2026): subgraph isolation "is fundamental to Federation's security model," and AI-powered discovery tooling makes an accidentally reachable subgraph more likely than ever to actually be found.
Beyond the boundary itself, two design defaults apply:
@key entities only when another subgraph truly needs to extend them.Use @inaccessible to keep internal-only fields out of the composed public supergraph. Verify the boundary empirically: probe every subgraph's address from outside the private network and expect connection failure, not a GraphQL response.
Partners or third-party apps contributing fields, data or subgraphs to the graph is a different design, with its own trust contract: see samber/developer-platform-skills@graphql-federation-offering.
Persisted queries replace a full query string with a pre-registered hash the server looks up and executes. The design decision is who gets which policy - and the deciding fact is that a closed allowlist only works when you control both client and server. graphql.org states it outright: trusted documents "can't be used for public APIs because the operations sent by third-party clients won't be known in advance."
So split the policy along the audience line from the top of this skill:
The cacheability point is worth the setup where read traffic is heavy: a hash-identified GET caches at CDNs the way REST URLs do, closing part of the caching gap conceded at step 1.
Treat allowlisting as defense-in-depth, never a complete answer: Apollo Router CVE-2025-32032 exhausted the query planner with recursive fragments before any per-operation guardrail applied, and allowlist bypass is itself a recurring vulnerability class. The ceilings of step 5 stay mandatory on every traffic class, allowlisted or not.
GraphQL's stated philosophy is continuous evolution of one live schema - field-level @deprecated instead of version bumps. The ongoing policy (deprecation workflow, usage telemetry, removal discipline, notice periods) is the versioning sibling's ground; your job at design time is to leave a schema that can evolve:
Anti-pattern checklist - each is a direct review finding:
errors array on a third-party surface.totalCount that forces an expensive count, payload fields that can't represent partial failure).authorId) instead of object references.Gates - iterate the design until all pass; each is binary:
errors array (unless the built-in-only rung was explicitly chosen for a first-party-only surface at step 4).These pass thresholds are set by this skill from the sourced design rules above, not published industry benchmarks - adjust the numbers (never the direction) to the team's context. After launch, watch guardrail rejections per week and which ceilings third parties actually hit; a ceiling nobody ever hits may be sized wrong in either direction, but that tuning is operations, not a design gate.
Expected output - a design decision record, one section per workflow step:
Reviewing an existing schema emits the same sections as findings instead: the anti-pattern hit, the SDL location, and the convention it violates.
See also, same collection:
samber/developer-platform-skills@api-integration-surface-strategy - the umbrella surface-selection decision across REST, GraphQL, gRPC, SDKs, and webhooks; step 1's gate defers to it when the question is broader than GraphQL-vs-REST.samber/developer-platform-skills@public-api-design-review - whole-surface consistency review; it hands GraphQL surfaces here and consumes this skill's checklist as its GraphQL rubric.samber/developer-platform-skills@api-rate-limit-policy - the cost-scoring and budget mechanics that meter traffic under the ceilings designed in step 5.samber/developer-platform-skills@api-error-design - the error-code taxonomy, envelope and message discipline behind the ErrorCode enum of step 4.samber/developer-platform-skills@api-versioning-policy - the continuous-evolution/@deprecated policy and notice periods step 8 hands off to.samber/developer-platform-skills@public-grpc-api-design - the same public-surface design job for gRPC, when the gate at step 1 points to service-to-service RPC instead.Design a public GraphQL API for third-party developers - the GraphQL-or-not gate, schema conventions (naming, nullability, Node interface, input/payload types), Relay cursor-connection pagination, uni
---name: public-graphql-api-designdescription: Design a public GraphQL API for third-party developers - the GraphQL-or-not gate, schema conventions (naming…---# skills/public-graphql-api-design/SKILL.mdVue d'ensemble
Design a public GraphQL API for third-party developers - the GraphQL-or-not gate, schema conventions (naming, nullability, Node interface, input/payload types), Relay cursor-connection pagination, union/interface error result types, depth and complexity ceilings as design decisions, the federation trust boundary (only the router is ever public), and a persisted-query policy that allowlists first-party traffic only. Use whenever the user mentions GraphQL, a public schema, Relay connections, query depth limits, persisted queries, federation, or GraphQL vs REST - even if they never say "GraphQL API design". Design layer only. Do NOT use for a REST surface review - use samber/developer-platform-skills@public-api-design-review instead.
FAQ
Téléchargez skills/public-graphql-api-design/SKILL.md auprès de l'éditeur, ou copiez le chemin et ouvrez le dépôt. PlugMCP répertorie le skill et n'héberge pas le fichier.
L'éditeur le maintient sur https://github.com/samber/developer-platform-skills.
Claude, Cursor, Codex et Grok Build peuvent lire un SKILL.md que vous ajoutez depuis le dépôt de l'éditeur. Grok Bot l'installe lorsque vous envoyez dans un chat le lien du dossier GitHub du skill.