graphql-gateway-specifications's Issues
[RFC] Persisted Operations
Summary
Persisted Operations (or, Persisted Queries) goal is to provide a security and hardening layer on top of the GraphQL engine.
Instead of executing a regular GraphQL operation, the clients are required to use a special string (hash) that's being translated into the actual GraphQL operation body.
For a more comprehensive/official spec, please refer to https://github.com/graphql/graphql-over-http/pull/264/files
Hash / Identifier
The hash for the persisted operation is usually generated at build/development time. The hash could be a generated, consistent string, an opaque value, or an actual computed hash based on the GraphQL operation body (for example, SHA256).
Store
The store is in charge of storing the actual mapping between the hash and the GraphQL operation body.
Simple Key->Value structure
A simple approach to providing the data to the store is to use a JSON key->value structure, as implemented by GraphQL-Yoga (https://the-guild.dev/graphql/yoga-server/docs/features/persisted-operations#quick-start).
This structure aims to be as simple as possible, and things like versioning can be part of the hash.
{
"someKey": "value"
}
Apollo Persisted Query Manifest
Apollo is managing their own format, based on JSON, for managing the stored data. This format is called apollo-persisted-query-manifest
.
{
"format": "apollo-persisted-query-manifest",
"version": 1,
"operations": [
{
"id": "e0321f6b438bb42c022f633d38c19549dea9a2d55c908f64c5c6cb8403442fef",
"body": "query GetItem { thing { __typename } }",
"name": "GetItem",
"type": "query"
}
]
}
- The
type
field andname
field seem like an extraction to make it easier later for the Studio (to avoid parsing again) - Apollo's store manifest is versioned as
1
. It's also hardcoded in Apollo Client as v1 (https://github.com/apollographql/apollo-client/blob/9229e0e1e65bb8ba199a5d2411d05debcb9d73c3/src/link/persisted-queries/index.ts#L269), so it seems like the version/structure does not change.
Execution
Prior to the GraphQL engine execution, the gateway needs to translate the hash into the GraphQL operation. To do that efficiently, the server needs to be able to load the data from the store, and then allow the client to specify the hash.
There are several ways of exposing the persisted operations as entry points:
Relay
Relay client sends a custom JSON structure to the server, and it is expected to be handled this way:
{
"doc_id": "hash",
"variables": {},
}
https://relay.dev/docs/guides/persisted-queries/#network-layer-changes
HotChocolate
Based on Relay's standard, but with id
field instead of doc_id
. (https://chillicream.com/docs/hotchocolate/v13/performance/persisted-queries#client-expectations)
Wundergraph's HTTP routes
By default, Wundergraph disables the GraphQL endpoint (/graphql
) and exposes HTTP-based routes for accessing the GraphQL operation.
This process also involved exposing the GraphQL queries as GET
operations, and GraphQL mutations as POST
operations:
query something {
__typename
}
Will be translated into:
/something
Variables are either passed as ?variables={"myVar": "1"}
or ?myVar=1
.
Apollo manifest
Apollo is using the GraphQL extensions
field to specify the store manifest version and the hash, over POST
:
{"extensions":{"persistedQuery":{"version":1,"sha256Hash":"ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38"}}}
Apollo also allows users to enable persisted operations over GET
.
Non-persisted operations
A gateway can choose to allow the execution of non-persisted operations.
[RFC] CSRF Prevention
[RFC] Normalized/Partial Caching
[RFC] Complexity-limit
Best-practices for public APIs
[RFC] HTTP Headers propagation / passthrough
[RFC] GraphQL Response Caching
[RFC] HTTP Caching
[RFC] Depth-limit
[RFC] Real-time transport (Subscriptions, `@live` / `@stream` / `@defer`)
[RFC] Rate-limit
[RFC] Security validations
Best practices for private APIs
[RFC] Authentication / Authorization (JWT-based)
[RFC] CORS
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. ๐๐๐
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google โค๏ธ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.