Skip to Main Content Ideas
Created by Ersin
Created on Oct 6, 2022

If/when there's a v3 content API, make saner defaults for refs and symbols

I've been working with refs and symbols a lot and there are two behaviors of the content API that seem strange to me:

  1. You have to opt into includeRefs: true and noTraverse: false.

  2. The API doesn't recursively evaluate refs ( will mitigate the situation but it would be better to just have this built into the API response logic).

I don't think there's ever been a case where I've wanted just the raw ref. I've always wanted the associated data. Same with symbols.

I understand why this can't be flipped on for the current API, but if y'all ever release a v3, I would request that you make includeRefs and traversal opt-out rather than opt-in, and that you recursively evaluate nested refs.

Also, in my experience working with devs who are new to Builder and coming from other CMSes, the API's and SDK's behavior around refs is one of the things that confuses them the most. It feels as if refs are a second-class citizen. I believe this may be a significant impediment for devs wanting to adopt Builder, especially when they come from other ecosystems where relational mapping is a prominent concept/workflow.

  • Attach files
  • Ersin
    Oct 11, 2022

    Just thought I'd add Steve's thoughts on this for anyone tracking the discussion:

    And my response:

    FWIW, I think the approach that Steve outlined in the forum (content API doesn't do includeRefs by default, but SDK does; change includeRefs to be recursive and also resolve more than just refs, e.g. symbols) makes a lot of sense.

  • Justin Radomski
    Oct 11, 2022

    I would definitely appreciate the ability to recursively evaluate refs. One example of a situation I've come across:

    I have a navigation structure built out in a CMS data model where each item is a ref to a page. This works great when just using the single ref pulling straight into a component/page, but it doesn't work well when using a separate builder component with a ref to select a navigation menu.

    Let's call this a footer widget. My footer has several menus in it, and I would like to be able to use a single component to have a widget to select that menu. This would be our first ref. The second layer ref would be each link that I've created in that first menu mentioned above. Unfortunately the current state of the API doesn't allow me to access the value of each link, so I'm using a useEffect hook to make a secondary call to the API to get that data.

    If that second ref value was available directly in the API, I would be able to render the entire page on the server.