Persisted Documents: encourage URL approach #305
Conversation
| For example, if the _GraphQL endpoint_ is `https://example.com/graphql` then a | ||
| persisted document request may be made to an endpoint such as | ||
| `https://example.com/graphql/sha256:517c56d2ba0779653b7698881207f749509f331bdaccbe951a82c378bc869556/FriendNames`. | ||
| For documents containing a single anonymous operation the final segment must be | ||
| omitted, e.g. | ||
| `https://example.com/graphql/sha256:71f7dc5758652baac68e4a10c50be732b741c892ade2883a99358f52b555286b`. |
There was a problem hiding this comment.
Should we maybe namespace persisted documents under /graphq/<prefix>/<sha>?
e.g.
/graphql/persisted/<sha>/<operation_name>/graphql/documents/<sha>/<operation_name>/graphql/persisted-documents/<sha>/<operation_name>
Main reason for this is that graphql-sse already encourages /graphql/stream, which in theory can conflict with a "custom" hash. Changing this would also leave the options open to add other URL based features later on and not conflict with the persisted documents.
There was a problem hiding this comment.
We do namespace it in HotChocolate for less collision potential. However, Twitter for instance puts it directly on the GraphQL route as as outlined in this document.
There was a problem hiding this comment.
Indeed, this is one of the things I was considering changing before moving this out of draft. I think I also want to change it to /graphql/persisted/<operation_name>/<hash> so that the op-name comes first for easier debugging. If there's no op-name, we can just use - for that part of the URL, e.g. /graphql/persisted/-/<hash>.
There was a problem hiding this comment.
I'm not a big fan of having the operation name first. 🤔
From a server perspective, we first look up the hash for the document, and then the operation name within that document. Having the operation name first seems wrong to me.
From a debugging perspective, it does not matter too much whether the operation name comes before the hash.
There was a problem hiding this comment.
Also if we are looking at Chrome DevTools, the last URL part is displayed. So replacing operation name and hash might even be counter productive.
There was a problem hiding this comment.
Good point, re Chrome devtools. Okay lets stick with the hierarchical approach, it makes more sense anyway 👍
This is just an early draft; I ran out of time.