Recipes

The following section provides sample queries and mutations that help you perform common workflows with the Frontend API.

Importing Content

In this scenario, you create a custom Content Group named Blog, and import entries into it.

Issue a mutation to https://api.getshogun.com/frontend to create the custom Content Group Blog. Define your Blog schema to have the following mandatory fields:

ID
Title
Author

Define your Blog schema to have the following optional fields:

Summary
Content
Published
Bookmark

Request the id and name of the new Blog Content Group in the response.

mutation CreateCmsModel {
  createCmsModel(cmsModel: {
    name: "Blog",
    searchable: true,
    visible: true
    cmsFields: [
      {
        name: "ID",
        type: string,
        localized:false,
        required:true,
        searchable: true,
        visible: true,
      },
      {
        name: "Title",
        type: string,
        localized:false,
        required:true,
        searchable: true,
        visible: true
      },
      {
        name: "Summary",
        type: string,
        localized:false,
        required:false,
        searchable: true,
        visible: true
      },
      {
        name: "Content",
        type: string,
        localized:false,
        required:false,
        searchable: true,
        visible: true
      },
      {
        name: "Author",
        type: string,
        localized:false,
        required:true,
        searchable: true,
        visible: true
      },
      {
        name: "Published",
        type: string,
        localized:false,
        required:false,
        searchable: true,
        visible: true
      },
      {
        name: "Bookmark",
        type: string,
        localized:false,
        required:false,
        searchable: true,
        visible: true
      },
    ]
  }) {
    id
    name
  }
}

The Blog Content Group is created successfully, and the new Content Group's name and id are returned in the response. For example:

{
    "data": {
        "createCmsModel": {
            "id": "b1e1f41b-ad00-4074-aafa-913d9948e840",
            "name": "Blog"
        }
    }
}

Using the id from the creation response, query the CMS fields on the Blog Content Group. For example, POST the following query to https://api.getshogun.com/frontend:

{
    cmsModel(id: "b1e1f41b-ad00-4074-aafa-913d9948e840") {
        id
        name
        
        cmsFields {
            id
            name
        }

  }  
}

Issue a mutation to https://api.getshogun.com/frontend to add an Entry to the Blog Content Group. Note that a CMS Entry has two properties: CMSModelId and value.

Property	Value	Example
`cmsModelId`	The ID of the Content Group	`b1e1f41b-ad00-4074-aafa-913d9948e840`
`value`	A JSON document where the names are the field IDs and the values are the field values.	`{"1b7525fd-3909-43d1-adc2-b89259aed4c5": "J. Smith"}`

The JSON value document contains the name-value pairs of all the CMS fields defined for the Content Group schema. At minimum, the value document must contain the id and name fields. In addition, it must contain any field that was defined as required when the schema for the Content Group was created. For example, the following fields are required for the custom Blog Content Group:

ID
Name
Title
Author

To add a Blog entry, specify a value for each of the fields in the JSON value document. Request the id, name, and value of the new Blog entry in the response. For example:

mutation CreateCmsEntry {
  createCmsEntry(cmsEntry: {
    cmsModelId: "b1e1f41b-ad00-4074-aafa-913d9948e840",
    value: "{
        \"ad56c174-4b63-45e2-9af9-ec827b732815\": \"Blog title\", 
        \"29fe6505-a746-4416-abe8-87eaf7017b50\": \"blog-post-id-1234\", 
        \"92824e2b-80ef-426f-8a95-135ed9372e33\": \"The blog name\", 
        \"1b7525fd-3909-43d1-adc2-b89259aed4c5\": \"J. Smith\"}"
  }) {
    id
    name
    value
  }
}

A new entry is successfully added to the Blog Content Group. For example:

{
    "data": {
        "createCmsEntry": {
            "id": "9844f4b6-573f-48bc-aaf9-7b651ff907d2",
            "name": "blog name",
            "value": {
                "ad56c174-4b63-45e2-9af9-ec827b732815": "Blog title",
                "29fe6505-a746-4416-abe8-87eaf7017b50": "blog-post-id-123",
                "92824e2b-80ef-426f-8a95-135ed9372e33": "The blog name",
                "1b7525fd-3909-43d1-adc2-b89259aed4c5": "J. Smith"
            }
        }
    }
}

Importing Media

In this scenario, you import a media image, create a CMS entry for it in the CMS Media Model, and then associate the imported media item with CMS Media Model entry.

Issue an uploadFile mutation to https://api.getshogun.com/frontend. Specify the URL of the media item to upload. For example:

{
    "query": "mutation($url: String!) {\n  uploadFile(url: $url) {\n    id\n    filename\n    height\n    mimeType\n    size\n    url\n    width\n  }\n}",
    "variables":
    {
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/ce/Star_wars2.svg/450px-Star_wars2.svg.png"
    }
}

The image uploads successfully, and the response contains the id of the media item. For example:

{
    "data": {
        "uploadFile": {
            "id": "b04d9465-cf05-4a55-a9bf-10dea9428555",
            "filename": "450px-Star_wars2.svg.png",
            "height": 214,
            "mimeType": "image/png",
            "size": 6450,
            "url": "https://assets.frontend.shogun.dev/b04d9465-cf05-4a55-a9bf-10dea9428555/",
            "width": 450
        }
    }
}

Find the CMS Media Model ID by issuing a GetMediaCMSModelId query. For example:

{
  "operationName": "GetMediaCMSModelId",
    "variables": {
      "name": "MediaImage"
    },
  "query": "query GetMediaCMSModelId($name: String!) {\n  cmsModels(filters: {name: {eq: $name}}, first: 1) {\n    edges {\n      node {\n        name\n        id\n        __typename\n      }\n      __typename\n    }\n    __typename\n  }\n}\n"
}

The query completes successfully and contains the CMS Media Model ID. For example:

{
  "data":
  {
    "cmsModels":
    {
      "edges":
      [
        {
          "node":
          {
            "name": "MediaImage",
            "id": "cb5aad54-01ce-4654-b1d7-a7ae20e63adc", # CMS MEDIA MODEL ID
            "__typename": "CmsModel"
          },
          "__typename": "CmsModelEdge"
        }
      ],
      "__typename": "CmsModelConnection"
    }
  }
}

Create a new media entry in the CMS Media Model by issuing a createContentGroupEntry mutation. Reference the CMS Media Model ID, and associate the uploaded media item's ID with the new entry. For example:

{
  "operationName": "createContentGroupEntry",
  "variables": {
    "cmsEntry": {
      # CMS MEDIA MODEL ID
      "cmsModelId": "cb5aad54-01ce-4654-b1d7-a7ae20e63adc",
      # MEDIA ID FROM THE uploadFile mutation
      "value": "{\"_type\":\"image\",\"alt\":\"\",\"height\":110,\"mimeType\":\"image/png\",\"name\":\"test2.png\",\"size\":16572,\"storageID\":\"b0ce78cc-8ec9-442d-8978-0166d2b16699\",\"width\":152}"
    }
  },
  "query": "mutation createContentGroupEntry($cmsEntry: CreateCmsEntry!) {\n  createCmsEntry(cmsEntry: $cmsEntry) {\n    id\n    name\n    value\n    __typename\n  }\n}\n"
}

The new entry is added to the CMS Media Model and is associated with the uploaded media. For example:

{
    "data":
    {
        "createCmsEntry":
        {
            "id": "4075a7ed-b843-43cf-bbd2-27e38bf0c50e", # MEDIA ENTRY ID
            "name": "21b4b53e-1d5c-4a26-b4ca-a7e5eb49d1ef",
            "value":
            {
                "_type": "image",
                "alt": "",
                "height": 110,
                "mimeType": "image/png",
                "name": "test2.png",
                "size": 16572,
                "storageID": "b0ce78cc-8ec9-442d-8978-0166d2b16699",
                "width": 152,
                "src": "https://ucarecdn.com/b0ce78cc-8ec9-442d-8978-0166d2b16699/"
            },
            "__typename": "CmsEntry"
        }
    }
}

Building and Publishing a Frontend Site

In this scenario, you publish your Frontend site. You identify the site to publish in the Site-ID header, provide your authorization credentials, and notes about why the site is being published.

Issue a publishSite mutation to https://api.getshogun.com/frontend. Include notes in the PublishSiteInput. For example:

mutation {
  publishSite(publishSiteInput: {name: "Black Friday Site", notes: "Publishing a new site."}) {
    sitePublication {
        id
        siteId
        submittedBy
        version
        status
        name
        notes
        submittedAt
        completedAt
    }
    message
  }
}

A new publish operation starts and a SitePublication object is returned in the response. The SitePublication object includes:

the id
which user submitted the operation
when the operation was submitted
the status of the operation

Because the publishSite operation has not yet completed, the completedAt field is null. For example:

{
    "data": {
        "publishSite": {
            "sitePublication": {
                "id": "53db6087-57b5-4892-a0f9-235f5de238e7",
                "siteId": "b1305072-e4f7-483b-ac5a-310ad0aa9e47",
                "submittedBy": "Jim Smith",
                "version": 66,
                "status": "RUNNING",
                "name": "Black Friday Site",
                "notes": "Publishing a new site.",
                "submittedAt": "2022-04-14T14:20:42Z",
                "completedAt": null
            },
            "message": "A publish has been started."
        }
    }
}

🚧
Only one publish operation can run at once for a site, whether it was initiated by the Frontend XM or by the Frontend API.

If a publishSite operation is already running, an error is returned. For example:

{
  {
    "data": {
        "publishSite": null
    },
    "errors": [
      {
        "message": "Another site publication is running. Started at 2022-04-19 16:12:31 UTC by [email protected]",
}

Discovering the State and Status of a Site Publication

In this scenario, you query the status of a sitePublication.

Issue a query to https://api.getshogun.com/frontend to retrieve the status of a site publication. Reference the SitePublication ID that was returned in the publishSite operation response. For example:

query {
    sitePublication(id: "0a629aa1-02cd-4ded-83c6-848c54f4f11b") {
        id
        siteId
        submittedBy
        version
        status
        name
        notes
        submittedAt
        completedAt
    }
}

The query returns the status of the sitePublication. The status includes:

version of the site publication
status of the operation
which user submitted the operation
why the site is being published
the date and time the operation was submitted
the date and time the operation completed, or null if not complete

For example:

{
    "data": {
        "sitePublication": {
            "id": "0a456aa1-02cd-4ded-83d6-999c54f4f11b",
            "siteId": "jim2be54-4e3a-409b-a93f-cb1f6eeafcb1",
            "submittedBy": "Jim Smith",
            "version": 10,
            "status": "RUNNING",
            "name": "Cyber Monday site",
            "notes": "Publishing Cyber Monday site.",
            "submittedAt": "2022-04-19T16:12:31Z",
            "completedAt": null
        }
    }
}