An experiment: what do `includeRefs` and `noTraverse` really do?

Technical Questions
5

howdy @ersin! so we do have some updates planned here, but a few notes that might help:

  • includeRefs=true in the API includes references (Rerence field type) values
  • options={{}} in BuilderComponent is only applied if the component itself does the fetching, not if you fetch with builder.get() and pass content as a prop. the preferred way is using builder.get(), we will be deprecating fetching within the react component (which include the options prop) over time
  • noTraverse=true tells the API to traverse the content to apply dynamic data like symbols, HTTP requests, custom server side js code, etc. at the API level it is off by default, but the SDKs send noTraverse=false aka augment the data
  • the reason why API calls don’t include references or traversal by default is it is computationally expensive, as well as problematic if you are doing reads and writes in the API (you don’t want to write back to us with refs/symbols/etc included). most use cases for using the content APIs directly is fetching large lists of content to either modify and write back, or to scan for basic thing like “give me all of our Builder page URLs” which don’t need any of these refs/traversal. the SDKs are most commonly used for fetching single entries at a time, and need all refs and traversal, so those default to sending noTraverse=false (and soon will default to includeRefs=true too)

over time, the v3 API aims to consolidate these params, likely there will just be one includeRefs param that will do everything (traverse and apply refs, symbols, other dynamic data). this will be off by default but for SDKs will pass this to be on by default

also slotted for the v3 content API is recursive refs as well (so includeRefs=true will include all refs not just the first layer)