Proposal for GraphQL API for cross-platform rich content #26

zetlen · 2018-09-19T15:46:35Z

⚠️ Addendum 2019/2/25: Added description of MVP Phase 1 implementation for upcoming PWA Studio releases.

This is a proposal for supporting CMS in our GraphQL layer through a common interface type designed to eventually interoperate with PWA Studio, Adobe Experience Manager, and/or other systems where business users create rich content with a WYSIWYG. It proposes a GraphQL format for traversing a tree and learning metadata about node implementations. A proposed schema:

interface VisualContentNode {
  role: String!
  depth: Int
  preload: [String]
  descendentRoles: [String]
  children: [VisualContentNode]
  html: String
}

An example request-response:

Request:

fragment NodeMetadata on VisualContentNode {
  nodeId
  role
  depth
  preload
  descendentRoles
}

content(nodeId: 1) {
  ...NodeMetadata
  html
  children {
    ...NodeMetadata
  }
}

Response:

{
  "content": {
    "nodeId": 1,
    "role": "Column",
    "depth": 4,
    "preload": [
      "banner1.jpg",
      "diagram.svg",
      "thumbnail001.jpg",
      "thumbnail002.jpg",
      "video.mp4"
    ],
    "descendentRoles": ["Banner", "Accordion", "Video", "Image", "Row", "Text"],
    "children": [
      {
        "role": "Banner",
        "depth": 0,
        "preload": ["banner1.jpg"],
        "descendentRoles": []
      },
      {
        "role": "Accordion",
        "depth": 3,
        "preload": [
          "diagram.svg",
          "thumbnail001.jpg",
          "thumbnail002.jpg",
          "video.mp4"
        ],
        "descendentRoles": ["Video", "Image", "Row"]
      },
      {
        "role": "Text",
        "depth": 0,
        "preload": [],
        "descendentRoles": []
      }
    ],
    "html": "Hello world! Text has already loaded."
  }
}

zetlen · 2018-09-19T16:06:44Z

@kandy suggests that instead of recursing through a tree, the API represent the nodes as an array with reference pointers to child nodes, and the client reconstruct the tree as necessary. Then depth could be controlled with a filter on the depth property:

query getContentNodes($id: String!) {
  nodes(filter: { depth: { lt: 4 }, and: { rootNodeId: { eq: $id }}) {
     depth
     role
     childNodeIds
  }
}

paliarush · 2018-10-09T18:03:21Z

proposals/rich-content-graphql-api.md

+
+## Proposal
+
+Add an interface to the GraphQL schema representing a recursive tree of PageBuilder content nodes. Each PageBuilder block type should add a concrete type to the GraphQL schema which implements this interface and adds additional fields for any required configuration. PWAs initially query only against the interface, and can therefore only receive the metadata. In the first few content loads, the PWA must make a "followup" request with more concrete query depth. As its cache grows, it does fewer and fewer of those requests.


If I understand correctly, we avoid using fragments syntax for querying relevant fields depending on the actual implementation of the generic content node interface. Why?

Because the list of potential implementations is unknown by the client. Extensions that add new PageBuilder blocks could add new implementations. Those implementations would have to include a GraphQL fragment that a PWA Studio PWA could use to add to its CMS query. That can happen at build time, but it should also be possible to do so at runtime.

paliarush · 2018-10-09T19:17:47Z

proposals/rich-content-graphql-api.md

+
+* **Why not use GraphQL introspection for this?**
+
+  - Per the GraphQL specification, the introspection query must provide only metadata, and not any data from resolvers. Implementing "partial introspection" via type tag names is a more efficient way of resolving recursive content nodes.


Introspection will also be disabled in production.

I should bring this up in a different issue, but we should at least permit the "standard introspection query" in production, which GraphQL clients use to generate documentation. It should be enough to cache the results of this query, since it will be invariant in production.

melnikovi · 2018-11-11T02:11:59Z

@zetlen please describe rendering current master format and returning definitions of React components based on offline discussion.

zetlen · 2019-01-09T20:38:11Z

@melnikovi Done!

jednano

Just a few questions.

jednano · 2019-02-08T16:38:37Z

proposals/rich-content-graphql-api.md

+            }
+            ```
+
+        3.  Re-render the fully hydrated second level of component when that query returns results.


Any way to avoid a re-render? I'm concerned about the page jumping as new content loads. I know you're not a fan of SSR, but it sounds like it would solve this problem.

In order to avoid this, the HTML fallbacks would have to have dimension. I think that the RichContent component could load a root PageBuilder stylesheet which would apply default dimensions.

As more PageBuilder components become "known" to the PWA runtime, it could add fragments to VisualContentNode queries like ...on PageBuilderGallery {} etc. which would get more and more specific configuration, including dimension, on the first render...

jednano · 2019-02-08T16:40:03Z

proposals/rich-content-graphql-api.md

+        ```
+
+
+        3.  Re-render the fully hydrated Slider component when that query returns results.


Ditto here. Always concerned about re-renders.

jednano · 2019-02-08T16:41:56Z

proposals/rich-content-graphql-api.md

+
+    3.  In series:
+
+    4.  Dynamically load and inject the `PageBuilder_Slider` React Component. (The bundle system and service worker will load from their caches if possible.)


How much content are we talking about here? I'm concerned about performance issues of putting too much responsibility on React to render things on the FE instead of on the first page load. I only speak from experience, because I've been 🔥 before on this point.

For Slider, we're talking about 3-4 Slides usually, with something like 10-20 is going to be a very rare edge case.

But the thing is is that the Slide itself can contain more internal components, like buttons, headings, texts, etc.

I think we'd have to see how it performed. The HTML fallback would already be in the DOM node that the Slider component takes over, so I would hope the React reconciler would reuse as much of it as possible.

How much content are we talking? The point is, we don't know at runtime.

jednano · 2019-02-08T16:43:11Z

proposals/rich-content-graphql-api.md

+4. For initial render, `RichContent` injects the sanitized fragment.
+5. After initial render, `RichContent` visits the DOM in the fragment to build a tree of PageBuilder rows, columns, widgets, and configurations.
+6. When the content tree is finished, `RichContent` dynamically imports the React components corresponding to all the PageBuilder widget types present in the content.
+7. When the runtime has loaded the components, `RichContent` re-renders the content tree as instances of live React components instead of HTML.


melnikovi · 2019-02-08T16:44:17Z

proposals/rich-content-graphql-api.md

+
+        3.  Re-render the fully hydrated second level of component when that query returns results.
+
+Subsequent requests for any content which lists any of those components in its `descendentRoles` will automatically include those fragment and clauses in the `content` query. Therefore, subsequent requests will contain the necessary configurations on the first pass.


Would be good to measure performance on the prototype. I feel like network communication expenses would be higher than potential slowness of getting large JSON in one request. I think we wouldn't have a lot of content. This also makes caching less efficient.

We should definitely measure the performance, and change approaches if it's terrible.

I think that caching might be better with GraphQL. If VisualContentNodes have unique IDs, then Apollo cache implementations can store their representations incrementally. Then, the PWA would reuse references to the same content entity.

melnikovi · 2019-02-14T15:51:18Z

proposals/rich-content-graphql-api.md

+
+### Considerations
+
+- The workaround involves DOM parsing and large string comparisons for update filters, which are both expensive operations which PWAs try to avoid.


Could you add pros and cons for each of the solutions?

melnikovi · 2019-02-14T16:07:25Z

@zetlen could you provide more context on "common interface type designed to eventually interoperate with PWA Studio, Adobe Experience Manager, and/or other systems where business users create rich content"? How Adobe Experience Manager and other systems will use proposed API?

Proposal for GraphQL API for cross-platform rich content

16d1ef8

buskamuza requested review from melnikovi and paliarush September 19, 2018 16:00

fixup: typos

a673f59

paliarush reviewed Oct 9, 2018

View reviewed changes

Add workaround information

af592f7

zetlen force-pushed the zetlen/visual-content-node branch from 785dc27 to af592f7 Compare January 9, 2019 20:40

zetlen mentioned this pull request Jan 9, 2019

Update global footer to consume data from the cms magento/pwa-studio#507

Closed

buskamuza assigned melnikovi Jan 31, 2019

jednano reviewed Feb 8, 2019

View reviewed changes

melnikovi reviewed Feb 8, 2019

View reviewed changes

melnikovi reviewed Feb 14, 2019

View reviewed changes

melnikovi self-requested a review February 14, 2019 16:07

fixup reworded phase 1 proposal

a37b753

melnikovi approved these changes Feb 25, 2019

View reviewed changes

melnikovi merged commit caae627 into magento:master Feb 25, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Proposal for GraphQL API for cross-platform rich content #26

Proposal for GraphQL API for cross-platform rich content #26

zetlen commented Sep 19, 2018 •

edited

Loading

zetlen commented Sep 19, 2018 •

edited

Loading

paliarush Oct 9, 2018

zetlen Oct 16, 2018

paliarush Oct 9, 2018

zetlen Oct 16, 2018

melnikovi commented Nov 11, 2018 •

edited

Loading

zetlen commented Jan 9, 2019

jednano left a comment

jednano Feb 8, 2019

zetlen Feb 15, 2019

jednano Feb 8, 2019

jednano Feb 8, 2019

belbiy Feb 15, 2019

zetlen Feb 15, 2019

jednano Feb 8, 2019

melnikovi Feb 8, 2019

zetlen Feb 15, 2019

melnikovi Feb 14, 2019

melnikovi commented Feb 14, 2019


		## Proposal

		Add an interface to the GraphQL schema representing a recursive tree of PageBuilder content nodes. Each PageBuilder block type should add a concrete type to the GraphQL schema which implements this interface and adds additional fields for any required configuration. PWAs initially query only against the interface, and can therefore only receive the metadata. In the first few content loads, the PWA must make a "followup" request with more concrete query depth. As its cache grows, it does fewer and fewer of those requests.


		* Why not use GraphQL introspection for this?

		- Per the GraphQL specification, the introspection query must provide only metadata, and not any data from resolvers. Implementing "partial introspection" via type tag names is a more efficient way of resolving recursive content nodes.

		```


		3. Re-render the fully hydrated Slider component when that query returns results.


		3. In series:

		4. Dynamically load and inject the `PageBuilder_Slider` React Component. (The bundle system and service worker will load from their caches if possible.)


		3. Re-render the fully hydrated second level of component when that query returns results.

		Subsequent requests for any content which lists any of those components in its `descendentRoles` will automatically include those fragment and clauses in the `content` query. Therefore, subsequent requests will contain the necessary configurations on the first pass.


		### Considerations

		- The workaround involves DOM parsing and large string comparisons for update filters, which are both expensive operations which PWAs try to avoid.

Proposal for GraphQL API for cross-platform rich content #26

Proposal for GraphQL API for cross-platform rich content #26

Conversation

zetlen commented Sep 19, 2018 • edited Loading

zetlen commented Sep 19, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

melnikovi commented Nov 11, 2018 • edited Loading

zetlen commented Jan 9, 2019

jednano left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

melnikovi commented Feb 14, 2019

zetlen commented Sep 19, 2018 •

edited

Loading

zetlen commented Sep 19, 2018 •

edited

Loading

melnikovi commented Nov 11, 2018 •

edited

Loading