search

craftcms / docs

Documentation for Craft CMS, Craft Commerce, and other official products.
https://craftcms.com/docs
38 stars 144 forks source link

[5.x]: GraphQL ping example needs an enabled, queryable schema #620

Closed olets closed 4 days ago

olets commented 2 weeks ago

Product

Craft CMS

Description

Following the directions at https://craftcms.com/docs/5.x/development/graphql.html#setting-up-your-api-endpoint, the ping returns

{"name":"Bad Request","message":"Missing Authorization header","code":0,"status":400,"type":"yii\\web\\BadRequestHttpException"}

because no queriable schema has been enabled.

After enabling the public schema and checking "Query for elements", the ping returns the expected

{"data":{"ping":"pong"}}
AugustMiller commented 4 days ago

Thanks for pointing this out! I went ahead and did a pretty significant overhaul of the GraphQL page, including the intro/setup section, and incorporated your PR.

olets commented 3 days ago

Nice update.

However the shortcoming remains. The documentation does not explain that no schema is queryable by default, and it doesn't explain how to make one queryable. https://github.com/craftcms/docs/commit/3c172af13ad0f8bebf136bbf5afe7b43425602b3#diff-2e69143c9b14f10f440221bd46cef7b964c6f759b02f613c17876bb3e87e39e0R92 is related but only acknowledges that there's potential for error.

Rebasing and merging #621 is one way to resolve this.

AugustMiller commented 1 day ago

That commit is only part of the rework—looking at the live page, the Getting Started heading has this:

By default, none of your content is publicly accessible via GraphQL—you must explicitly authorize resources by configuring one or more public or private schemas.

When discussing the first requests, we say:

Assuming your project lives at https://my-project.ddev.site and your route was configured like the example above, you can confirm the public schema is working by sending a {ping} query to it: […]

That is followed by the pass/fail section you mentioned—which on its own I think is an appropriate strategy… experimentation is at the core of all this, and supporting both outcomes (rather than presuming success) feels like an intellectually honest way to introduce someone to these external queries.

I've pushed one more change that makes it clear the public schema is disabled by default!

Let me know if this addresses your concerns?