Primo REST API

[mateomorris]

Primo v2--beta.17 introduces a the ability to consume your site content as a REST API directly from your Primo Server. Previously, to consume your site content from another source (like SvelteKit) you had to fetch the site file published with your site builds, but that's kind of hacky since it wasn't the original intention for the file (and the file could get pretty big for medium to larger sites).

You can access your content by fetching it from the '/api/' endpoint (e.g. https://try.primocms.org/api/theme-nonprofit). The response looks like this:

site: {
  favicon: {
    url: '...',
    alt: ''
  },
  _meta: {
    id: '...',
    name: 'My Website',
    url: 'sitename',
    created_at: '...'
  }
},
page: {
  _meta: { 
    ..., 
    subpages: [ ... ]
  },
  title: 'My Page',
  description: 'This is my page'
},
sections: [
  {
    _meta: { ... },
    heading: 'Welcome to my website',
    image: { url: '...', alt: '...' },
    content: { markdown: '...', '...'  }
  },
  ...
]

The properties within site, page, and sections represent field values set in your Site, Page, and the blocks on the page, respectively. Each includes a _meta tag containing metadata about the site, each page, and each section, with which you could do things like: fetch each subpage under the 'blog' page individually (using page._meta.subpages), access the header on the homepage by its id, or grab each section which is an instance of the 'content' symbol (using sections._meta.symbol).

This is just a first pass at this, so expect it to change as it gets used and input is given by the community. Updates will be posted here and the Primo forum so you can track any breaking changes. I'm happy to hear how it could be improved as things come up; some things off the top of my head that I could see being needed in the future are:

• Authentication (i.e. creating an API token to include in the authorization header so site content isn't publicly exposed)
• Query params for fetching particular types of site data (including symbols, fields, and code)
• Versioning for reliability in production