Rename resolveFields to query in the itemAPI #5451
Conversation
🦋 Changeset detectedLatest commit: 72fb99c The changes in this PR will be included in the next version bump. This PR includes changesets to release 17 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
This pull request is being automatically deployed with Vercel (learn more). 🔍 Inspect: https://vercel.com/keystonejs/keystone-next-docs/EtkzAbUZEmviH9tE3gpXdqmZnMb4 |
|
This pull request is automatically built and testable in CodeSandbox. To see build info of the built libraries, click here or the icon next to each commit SHA. Latest deployment of this branch, based on commit 72fb99c:
|
…ystonejs/keystone into rename-resolvefields-to-query
| } | ||
| if (query !== undefined) return query; | ||
| if (resolveFields !== undefined) return resolveFields; | ||
| return 'id'; |
There was a problem hiding this comment.
I would have defaulted it to false
After feedback and an internal discussion, we're going to rename the
resolveFieldsargument in the Items API toquery.Hopefully this helps make the Items API more intuitive and self-documenting.
For background, the Items API makes Keystone's GraphQL API available to Node.js directly, without the overhead of making a full GraphQL query over http. Because of the more direct syntax, you don't need to write out a full GraphQL query, but you do still need to nominate the fields you want resolved, in GraphQL syntax (the "field selection"). Unlike with most ORMs (which this provides a similar interface to) you get the full functionality of nested queries through relationships, and can use virtual fields.
It also offers a more direct option of returning the raw data from the database (effectively equivalent to
select *in SQL) which we refer to as the "unresolved list item". This is required for certain back-end functionality to to work, e.g comparing a password hash (which is never available through the GraphQL API).The challenge is given an API that can return two significantly different types, how do we make it intuitive to use? Hopefully naming the argument that controls this behaviour
querymakes it clearer:(A) By default, the API will just return the
idof each result(B) If you want to query more fields (including virtual fields or related items) you pass the
query: 'fields'argument, with GraphQL Query syntax for the fields you want to query from the graph(C) If you want the raw / unresolved list item data, you pass
query: falsewhich bypasses the field resolvers