Agent WranglersGraphQL and gRPC
Design rules for GraphQL schemas and gRPC services. Mutations only by POST, deprecate before removing, batch loads, stable field numbers and deadlines.
- Required 2
- Recommended 7
- Optional 1
Required
Accept GraphQL mutations only by POST with a JSON body
API-81Run GraphQL mutations only from POST requests with
Content-Type: application/json. Refuse a mutation sent by GET with 405 and anAllowheader, and refuse POST bodies of any other content type.Never reuse or change a protobuf field number
API-87Never give a protobuf field number a new name, type or meaning. When you delete a field, list its number and name under
reserved.
Recommended
Deprecate GraphQL fields before you remove them
API-82Change a GraphQL schema by adding types and fields, never by versioning the endpoint. Mark a field you plan to remove with
@deprecated(reason:)and remove it only after 90 days with no use.Page GraphQL lists as cursor connections
API-83Return every list that can grow past 100 items as a connection with
edges,node,cursorandpageInfo. Require afirstorlastargument with a cap.Load related records in batches
API-84Resolve nested fields through a batching loader, created fresh for each request, so one query sends one database call per field level. Never one call per item.
Give every GraphQL error a stable code
API-85Put a fixed, documented code such as
NOT_FOUNDorFORBIDDENinextensions.codeof every GraphQL error. Clients act on the code, never on the message text.Check every schema change for breaking changes in CI
API-88Compare each change to a GraphQL schema or protobuf file with the version on the main branch in CI. Fail the build on a breaking change unless the pull request carries an approved label.
Set a deadline on every gRPC call and pass it on
API-89Give every gRPC call a deadline in the client. A server that calls other services passes the remaining time on, and stops work when the deadline has passed.
Answer with the standard gRPC status codes
API-90Return one of the 17 standard gRPC status codes with the meaning grpc.io gives it. Never return
OKwith an error inside the message, and never invent new numeric codes.
Optional
Allow only known queries from your own apps
API-86When only your own apps call a GraphQL API, register each query at build time. The server runs only registered queries, sent by their hash.
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/api-design/graphql-and-grpc">Agent Wranglers API design playbook</a>. In code you write, add a comment next to it with the same link.