WebReinvent Internal Docs
Api

Content Api

With the Content API, you can make requests to retrieve data about any of your models within Builder. The Content API supports advanced query filtering with URL parameters to help you get exactly the data you need.

Use cases for querying data could include searches, populating content for a collection, or getting all links that meet certain criteria.

To access this data, write queries with dot notation and, optionally, MongoDB style operators.

Query requirements

To use the Builder Content API to retrieve data from your models, be sure to always provide the following request parameters in your queries:

  • Required: my-model-name (replace with your model's name)
  • Required: apiKey query param (replace with your Public API Key)

Content API query params

This section covers the available Builder Content API query params.

apiKey

Use your API key when integrating with Builder.

//import the SDK
import { fetchOneEntry} from '@builder.io/sdk-vue';
const entry = await fetchOneEntry({
  model: 'data-model', //Specify your model name 
  apiKey:config.public.apiKey, //here provide your api key
})

Note: fetchOneEntry is used to fetch only one entry, if you want to fetch more than one entry use- fetchEntries 

import { fetchEntries } from '@builder.io/sdk-vue';
const entry = await fetchEntries({
  model: 'data-model', //Specify your model name 
  apiKey:config.public.apiKey, //here provide your api key
})

Query

With query you can query for your data in MongoDB style.

 import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,
   query: {
    data: {
      name: 'John'
    }
  },
})
//It will query the entry which has a name field equal to John

Builder supports the following operators: $eq $gt $in $lt $lte $ne $nin $and $not $or $nor $exists $type $elemMatch $gte $regex $options. For more information, including examples, see the Builder Querying Cheatsheet.

userAttributes

Optionally use to send targeting attributes.

import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,
   userAttributes: {
    urlPath: '/about',
    device: 'desktop',
    userLoggedIn: true
  },
})

fields

Only include these fields.Only these fields will be present in the response.

import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,
   options: {
    fields: 'name, data.age'
  },
  
  //if you have a custom field use it like data.customField
  
})

omit

Omit only these fields, These fields will not be present in the response.

import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,
   options: {
     omit: 'data.age, name'
  },
  
  //if you have a custom field use it like data.customField
  
})

limit

Max number of results to return. The default is 30 and the maximum is 100.

import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,
 limit: 10  
})

offset

Use to specify an offset for pagination of results. The default is 0.

import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,
 offset: 10  
})

includeRefs

Include content of references in response. if one of your fields is a reference type so it will return the referenced content also in the response. It is true by default

import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,  
 includeRefs: false
 //It means now  it will  not return the content in the response.
})

cacheSeconds

Seconds to cache content. This sets the maximum age of the cache-control header response header. Set value higher for better performance, and lower for content that changes frequently.

import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,  
 cacheSeconds: 10
 //It means server will store a copy upto 10sec in cache, 
 //if an api is called again to enhance performance
 
})

staleCacheSeconds

Builder.io uses a stale-while-revalidate caching strategy at the CDN level. This means that even if the cached content is considered stale (expired), it can still be served to users while the CDN simultaneously revalidates the cache in the background.

import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,  
 staleCacheSeconds: 86400 //default value- 1 day
})

sort

Property to order results by. Use 1 for ascending and -1 for descending.

The key is what you're sorting on, so the following example sorts by createdDate. and because the value is 1, the sort is ascending.

import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,  
 sort: {
    createdDate: 1
  }
})

includeUnpublished

Include content entries in a response that are still in draft mode and unarchived.

import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,  
  options: {
    includeUnpublished: true
  },
})

noTraverse

Though the default is true, you can pass false to include Symbol JSON in the response. This is helpful if you want to render your page all at once such as in server-side rendering.

import { fetchEntries } from '@builder.io/sdk-vue';
 const entry = await fetchEntries({
 model: 'data-model',
 apiKey:config.public.apiKey,  
  options: {
     noTraverse: true
  },
})

Custom Components

HTML API

Copyright © 2024