Importing Content

Introduction

To enable the best possible user experience, your CMS will have the ability to automatically import content, e.g. with an API or a JSON file that can be uploaded to seed content into the CMS. This flow allows us to:

1. Automatically provision the CMS
2. Automatically create sample content in the CMS

both of which, in tandem, create an exceptional onboarding experience that your users will love. Oftentimes this import utility can be naturally coupled with an export utility so that content can be exported and then imported.

Let’s go into some technical detail.

Importing content API

Exposing an API is the simplest and likely quickest way to achieve a hook that Gatsby Cloud can invoke to create/reset content. It may be a flow like:

1. An exposed POST endpoint that accepts Content-Type: 'application/json'
2. Headers or a bearer token so Gatsby Cloud can pass OAuth credentials
3. Additional parameters to refer to a specific space or content area

This flow will be specific to your specific CMS, but an example to make this concrete can be helpful. Suppose we have a CMS “Great CMS” which is all the rage right now.

The API

We expose a POST to all created spaces/instances. For instance, suppose we have a space ID of 1234, the POST endpoint for the API to import content may be:

https://data.great-cms/api/v1/1234/import

We can trigger this with a POST endpoint like so:

import axios from "axios";

axios({
  method: "POST",
  url: "https://data.great-cms/api/v1/1234/import",
  headers: {
    Authorization: `Bearer {MY_SUPER_SECRET_JWT_HERE}`,
  },
  data: JSON.stringify({
    types: [
      {
        id: "person",
        type: "Person",
        fields: [
          {
            id: "name",
            name: "name",
            type: "string",
          },
          {
            id: "bio",
            name: "bio",
            type: "string",
          },
        ],
      },
    ],
    entries: [
      {
        type: "Person",
        fields: [
          { value: "John Due", name: "name" },
          {
            value: "John Doe is a pretty cool guy. Does a lot of great things.",
            name: "bio",
          },
        ],
      },
    ],
  }),
})

;

To improve this experience and make it as seamless as possible, it can oftentimes also be helpful to create Node.js utilities or tools (or some type of command-line interface) to make using this API as easy as possible. However — as long as the API exists, that’s a solid user experience and one that is worth striving towards.

Real-world Examples

Consider checking out some of the below resources for real-world examples:

• contentful-import
  • A utility to import a JSON schema (and content implementing that schema) into Contentful
• @sanity/cli importing data
  • Sanity recommend importing data with the CLI tool, which will create the schema and seed content implementing that schema