Gql doc-only probably, concerning token permits

[narration-sd]

Description

@andris-sevcenko this is just because Github acts funny on mentioning your name on a different repo, so wanted to be sure you had the benefit, not as much my comment as seeing a case where people will get confused etc..

Here's the case: markhuot/craftql#323 (comment), starting actually at the top with his initial frustration...

As a p.s., I'm doing a little support over there, to lay groundwork hoping I won't have to soon with a certain release, same principal as Hal the robot....

[andris-sevcenko]

Got pinged by github just fine :)

I mean, there's no reason to assume that anything would be exposed - not sure if it warrants explicitly mentioning in the docs?

[narration-sd]

I don't know, I just had a look at a vm where I don't think I've messed with it, and Public Schema isn't permitted anything. And I presume helloWorld works even if its not enabled??

It does seem though that a concise mention of Public Schema rather up front in the doc would be wise, saying that if you do enable elements etc. there, you'll want to consider security, as then anyone who picks up your [gqlapi!] url will be able to discover, and run queries or worse (upserts), on any of those things.

Not least because CraftQL is entirely sealed up for this, and persons may expect it.

Hope this isn't too rum, as I am just having completed two days of beating Gridsome's more intricate aspects to the mat... 🐲🐲

[brandonkelly]

There already is a concise explanation of this in the docs (https://docs.craftcms.com/v3/graphql.html#define-your-schemas):

The Public Schema defines which content should be available publicly.

[narration-sd]

Well, yes, there is. Then I think we have to ask, why wouldn't this help on the case mentioned, or others I've recently dealt with which actually involved Gql?

• the 'of course', first, is that persons just don't read documentation, at least deeply enough to get its implications. This by some close experience here can often be true among those who ride the edge of 'design' and 'development' -- which is particularly going to be the set attracted by GraphQL.

• There are a lot of implications in that short doc section (which I hadn't seen since I began working with Gql before it existed (I think)).

  • Those implications are the things that will bite people if they just patch code tips together and make a stab.

• We do have a nice mechanism, scanning your doc section reminds: the decorated asides that Vuepress provides.

• The 'conversation' between those and the straight, for programmer, text is likely to be especially illuminating, and means you don't have to try to deliver everything in one rush of words.

  • There could be a note at gold Warning level to carefully consider what you permit in Public Schema, naming the consequences.
  • There could be one at Tip level commenting that of course if you don't permit anything, it's only going to allow the { ping } query without authorization, thus covering that stumbling point/useful feature as well. [I just checked on a vm that this is what it presently seems to default and do]
  • btw, it's an example of 'implications hiding within' that this Tip suggestion so far stilldoesn't draw out that Gql's 'I'm alive' query isn't the same as CraftQL's.
  • add your own as you think out or find out yourself how persons can stumble or behave

• ok, and on the programming/design thinking side (effort/philosophy), there are also things that can help.
  -- I think I've mentioned to Andris that even if error messages float up from within webonyx, they can be with minimum effort recognized, and important ones added to, for illumination.
  -- 'Not authorized' is a great candidate. You could save frustration and send people back into the doc as they need it, e.g. by mentioning that this is 'likely because there isn't yet a Craft Gql security token provided with your query'.
  -- Naming your system in the message for such cases can be a big help, likely you'll reckon.
  -- But also, defaulting the routing rule so that it's e.g. 'gql', not 'api' which is the same as CraftQL, is a pretty evidently positive move I've already mentioned out of cases . You can see the confusion this can cause if you think for your own implications.
  -- cases for the preceding: Error after purchasing license > "Craft Pro is required for this" markhuot/craftql#319 and Cannot query field "entries" on type "Query" markhuot/craftql#322

-- It's not any place I'm asking you or especially Andris to go, but for the unavoidable nonsequitor errors in mutually unaware but coupled systems as Live Vue arranges, I've simply had to do at-the-moment handholding and focus documentation, which is what Hal the Robot does. Just recognizing a few key error messages and exttending them, though, is a piece of that action which seems it would be good for problems that occur at Craft's boundaries here.

Ok, and last point is that you don't always get 'Not authorized' when that's the base problem. I'll write that up in a separate issue, as testing for what's written here turned up the source of a mystery seen before.

Cheers both, @andris-sevcenko and @brandonkelly . I don't raise issues just for fun, you know...

[narration-sd]

Just discovered something nice which can help with the doco tips part of this...

By some care reading (!) over the latest Vuepress documentation, I noticed that you don't have to be restricted to the WARNING letters which made me uncomfortable about recommending the warning level even if it's the appropriate one for purpose.

if you specify for example like this:

::: warning Nota Bene
...something  you want to talk about which doesn't need scare words or benefit from them...
:::

You get what you'd like:

You guys may know this already, but I was impressed...

[narration-sd]

...and, just to add to the meta that's in discussion now, I realize how I learned this little useful factoid:

• I did not, at first, scrutinize the Vuepress doc on the subject for its hidden meanings
• I did, grab the first thing that appeared to my eyes, and 'coded it in' -- wrote to use the golden (vs. apparent red) WARNING level. Shaking my head about them having also a red one.
• Where I did realize, was later when I picked up the last, extra of the primary three, example -- and could snap-see that it had a different title.
• Having by potent visual cue realized there was something to pay attention to, I read closely enough to write the Nota Bene example, and then pass it to you.
• I still had not really read that late example closely. When I did, just to check something I was about to say to you, only then did I see it really did explain about making personalized tags.

I think I am not exactly alone, in present day, with operating on this multi-mode wavelength of skim-reading. It is a habit of our over-information activities. Some issues with eyesight remaining also contribute, I'm aware, but don't think I'm alone in this either.

Thus, my thought above about the value of giving inter-conversational alternate messages and highlights, as being much more effective. And also easier to write, really...

The Vuepress doc section referred to is here: https://vuepress.vuejs.org/guide/markdown.html#custom-containers