Concepts

A quick overview on the concepts of GraphCMS.

Projects

Your content lives within a project. In a project you can:

  • Define the shape of your content by adding schema models and schema enumerations

  • Add fields and your created enums to your models

  • Manage and browse your project´s content

  • Upload and assign media files

  • Invite others to your team

  • Use the integrated GraphiQL playground to run queries and mutations against your project´s endpoint

Schema Models

Schema models describe the shape of your content. They consist of several fields while each field can store various types of data (e.g: text, numbers or images). A field can also be a reference to another model, which allows you to build a complex content graph. The fields you associate with a model will also define how its content editing user interface will look.

Fields

Fields are the building blocks of your schema models. Each field type can store a specific type of data. GraphCMS offers the following field types:

  • Single Line Text: names, titles, list of names...

  • Multi Line Text: comments, formatted text...

  • Markdown: long form content, formatted text...

  • Integer: ID, product number, quantity...

  • Float: precise numbers, prices, percentages...

  • Checkbox: true or false, yes or no...

  • Date: post date, date of birth...

  • Date and Time: events, opening hours...

  • Json Editor: data in JSON format

  • Asset Picker: any asset, e.g. image, video...

  • Dropdown: selection on a predefined set of values (Enumerations)

  • Reference: for referencing other schema models. E.g. the author of a blog post

Screenshot

Webhooks

Webhooks are available starting from the Basic Plan. New Projects will be started in a two-week trial, where you get access to all higher-tier feature like Webhooks or Content Localization.

Webhooks are a powerful concept that enable you to execute your own business logic an event occurs.

Setting up a Webhook

Creating a webhook in GraphCMS is straight forward. Switch to the WEBHOOKS view and click the CREATE WEBHOOK button.

1. Name

Give your webhook a name.

2. Description

Help yourself and others know what the webhook does by giving it a description.

3. URL

Define what url should be requested by the webhook.

4. Headers

Define the key value pairs for which header values your URL will expect.

GraphQL Endpoint

You can find your API endpoint on your project dashboard and settings. You are also able to test it out in your projects API Explorer.

Public API Permissions

By default your project endpoint will be set to PROTECTED. To change this, head to your project settings.

Permanent Auth Tokens

To connect your client applications with your GraphCMS backend, you will need to create permanent auth tokens. This will allow your external client to:

  • READ existing content entries

  • WRITE write new and update existing content entries

  • OPEN read, write and update existing content entries

How to work with permanent auth tokens

Be careful! Anyone that gains access to one of your WRITE or OPEN tokens will be able to execute all of these operations and manipulate your content. So it is never a good idea to store a WRITE or OPEN token on the client side, i.e. a JavaScript client application.

System Artifacts

Each GraphCMS project comes with a few system artifacts, that users should be aware of. Those are models and fields that are created automatically by the system.

Asset Model

The Asset system model is where your uploaded files get stored. Each time you assign an asset field to one of your schema models, a relation to this model is created.

The fields of the Asset model are:

  • fileName the name of the file

  • handle the unique identifier of the file

  • url the public url of the file, which is always media.graphcms.com/handle

  • size the size of the file

  • mimeType the internet asset type of the file

  • isPublic a flag that indicates if the file is available for the public (currently always true)

System Fields

Each content model in GraphCMS has the following system fields by default:

  • id stores the unique identifier of a content entry

  • createdAt the date the content entry was created

  • updatedAt the date the content entry was updated the last time

  • status indicates if the content entry is published