Under Community Review

Expand linked ("nested") Topics in the Public Content API

Similar to this idea for Dynamic Experience Delivery queries for Tridion Sites, this request is for the ability to retrieve the nested/linked Topics in the GraphQL-based Public Content API (PCA) for Publications, especially with the semantic "ish-" queries.

The use case is to give application or portal developers using the Content Delivery APIs a way to get back a Publication and its contents in fewer queries. This would simplify development and also reduce the number or requests sent to the CD endpoint "over the wire." There doesn't seem to be a simple way to automatically get linked Topics as objects, rather than as IDs which need to be resent over additional queries for the Topic content. 

For example, we have a project where we wanted to get back a Publication, which may have 10-20 Topics on it, as well as its content in one query.

Maybe others can add their thoughts on what an ideal query (and any parameters) might look like, but so far:

  1. ishTocStructure seems like a promising candidate to improve, since it brings back a table of contents which represents a Map and its Submaps from Tridion Docs. However, as of DXD 12, this seems to only give us back IDs that we then use to query the specific Topics separately.
  2. Alternatively, ishTopics can get all the Topics and content for a given Publication, but the topics don't seem to come back in the same order as ishToc or ishTocStructure. Maybe there could be a parameter to get the Topics in the order of the map.  

Either way, I think we'd want these improvements mostly on the Tridion Docs Semantic Content Model queries (introduced with Tridion Docs 15 and DXD 12) since these are much more Docs-centric.

Alvin Reyes
  • in reply to Damian Jewett

    Good question and thanks for the examples,  Many of our Tridion Docs implementations indeed have hundreds to thousands of topics per Publication for sure. However, I've also seen some with very small Publications, focused around a specific instruction (think procedures for training team members). These Publications still need a bit of reuse in terms of topics and conditional parts, but they have their own content life cycle and reviews that should be just for that set of content. 

    In those cases, I think the expanded query would be useful. I wouldn't recommend using it for the larger publications though.

    I submitted this idea with input from a customer, so there's at least one tangible use case (though perhaps there are more?)!

  • Maybe slightly off topic, but one thing I've done in the past, when working with DXA with the Dynamic Documentation module, is to copy the existing TOC endpoint and update it to return all TOC items, recursively:

    https://github.com/RWS/dxa-modules/blob/develop/webapp-net/DynamicDocumentation/Controllers/ApiController.cs

    This may not get you all the topics in a single query, but at least gives a list of all topics, recursively. Stepping through the code and into the libraries might also provide some clues as to which GraphQL queries could be helpful.

    I'm curious what the use case is for returning all topics and their content in one query, as typically documentation is set up to display one topics at a time. Once you have hundreds or thousands of topics, it's probably not useful or a good idea to retrieve all the content in one query, as this would be slow and a very heavy query.

  • We do this within a topic directly to get back nested topics/drill into related topics, and so on. It follows on from the semantic content modelling. We could allow people to go further and pull back topics and so on from a publication. We could also do the same for the TOC and indeed, pull back the TOC from a publication too. Seems like a good thing to add since as you say, it would allow access to all content from a single request.

    Something along the lines of:

    {
      ishPublication( ... ) {
           toc(filterParams) {
               title
               url
               topic {
                   title
                   relatedLinks {
                       url
                   }
                   xhtml
               }
           }

           topics( topicFilter ) {
               title         
               relatedTopics {
                  ...
               }
               xhtml
          }      
     }

    With some extra optional filter(s) we can extend this. Since the entire Ish model is built with semantics in mind, this wouldn't be too much effort since the general mechanism is already in place.

  • Note: we submitted this as part of a customer project, based on a question and interest in getting a Publication and linked Topics in a singe query. Comments and votes appreciated if this would or wouldn't help others, recognizing content models may differ across customers.