Validation for publishing a GraphQL Document

[Jason Bahl]

Currently GraphQL Documents can be published without any "required" information, such as a GraphQL Document or query alias.

We should add validation that prevents a document from transitioning to the "publish" state if it doesn't have a valid graphql document.

Since the Query Aliases are generated on save, perhaps we might only need a valid document, but without both the queries shouldn't be in a published state.

[Mark Kelnar]

Currently, persisted query documents (queries) can be created two ways.

1. APQ POST request
2. WP ADMIN editor

Existing query strings can be saved/modified in WP ADMIN (2).

The query taxonomies associated with a saved query can be modified via Mutations (3), but not the query string.

Thoughts on how to handle saving queries and handle errors:

• APQ POST (1) Saves queries with a 'PUBLISH' status. Not draft.
  • Create new query and save:
    • status to publish
      • validate form fields
      • if form errors, return http error code 500 and graphql error message like "Syntax Error:"
      • if no errors, save data as publish status and return http code 201
• WP ADMIN (2) work flows:
  • Create new query and save:
    • auto draft
      • do not validate all the form fields
      • do not show admin error(s)
    • save draft
      • validate form fields
      • show admin error(s)
      • if form errors, save data as draft status
      • if no errors, save data as draft status
    • status to publish
      • validate form fields
      • show admin error(s)
      • if form errors, save data as draft status
      • if no errors, save data as publish status
  • Modify query and save
    • auto draft
      • do not validate all the form fields
      • do not show admin error(s)
    • convert from draft to publish
      • validate form fields
      • show admin error(s)
      • if form errors, save data as draft status
      • if no errors, save data as publish status
    • publish status stays same
      • validate form fields
      • show admin error(s)
      • if form errors, do not save data, revert to previous
      • if form errors, query string in editor reverts to last working version or blank. user can change to draft status to be able to save invalid query string
      • if no errors, save data as publish status
    • publish status to draft status
      • validate form fields
      • show admin error(s)
      • if form errors, save data as draft status
      • if no errors, save data as draft status

[Jason Bahl]

@markkelnar good job thinking through the various state transitions.

This all seems to line up with what I have in mind.

one thing I'm not fully sure I follow is:

if form errors, query string in editor reverts to last working version or blank. change to draft status to be able to save invalid query string

Can you elaborate what you mean here? If the user is modifying an already published document, why would we change it to draft?

[Mark Kelnar]

We shouldn't save the invalid/broken graphql query in a PUBLISH status.

When the user clicks save, we don't have a way to persist that invalid/broken query in the editor box without saving it to the WP post, therefore losing the previous "working" query. One flow would be to keep the previous working query string, not including the edits being made. Leave it as published. And just show an error message at the top of the editor screen. But the query that was being edited is "lost". The user doesn't see the query anywhere, has no good information about what was broken and can not see what the query was when it was saved. They would be confused as to what was wrong and how to continue editing the query, even if it were broken. This flow would give them a chance to continue editing the "broken" query in a 'non-published' status until they get it correct. Once it is valid, it can be 'published'.

Another thought is that queries, once "working and published" can not be edited. But instead must be cloned or saved as a new different query. I think we have that ticket/issue somewhere. Maybe that would solve this scenario.

Another thought, we open the graphiql editor to "Edit queries", utilizing the functionality there to create/edit queries. And include a "save" in graphiql ide.

[Jason Bahl]

Another thought is that queries, once "working and published" can not be edited. But instead must be cloned or saved as a new different query. I think we have that ticket/issue somewhere. Maybe that would solve this scenario.

That's what I was thinking.

If the document string (the post_content) is modified in a valid way, we would save it as a new post. (I think there probably would need to be a dialog or something where the user could confirm they want to save a new query. Something like: "Would you like to save this as a new query or dismiss the changes?" or something to that tune. This could come later, if needed, but would be a good UX addition, I think.

If the document string (post_content) is modified in a non-valid way, we should keep the previously valid document string, but display an error about why the modification did not save.