Building Blocks

This part of the documentation will be about the core concepts of Gentics Mesh.

You will learn:

  • What is needed to setup a project?

  • What are the core concepts and most relevant parts of the API to get started?

  • How to design your content model?

  • How to manage users and permissions?

Project

In Gentics Mesh a project is the place to organize all the contents and media assets for a given project, e.g. a product catalogue website, your blog, your company intranet, an e-commerce website, a social community app - you name it. You can create as many projects as you would like.

A project represents the base element of your content structure, which includes your actual content items called nodes as well as tag families. The tags for tagging content items are grouped in tag families and are defined for a specific project. Schemas are assigned to projects in order to specify what types of nodes can be created. Users have access to a project and its contained content items depending on the role(s) they’ve been assigned.

Gentics Mesh creates a root or base node for each project. As you will learn soon, each node needs to have a schema it follows. Hence, when creating a new project you need to name a schema. You can use the folder schema which is shipped with Gentics Mesh.

API endpoints

Description API endpoint

Create a project

POST /api/v1/projects/

Get all projects

GET /api/v1/projects/

Get a project

GET /api/v1/projects/:projectUuid

Update a project

POST /api/v1/projects/:projectUuid

Delete a node

DELETE /api/v1/projects/:projectUuid

Response Sample

{
  "uuid" : "303b16500c3e429bbb16500c3e529b3d",
  "creator" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "ef739d8f8b174e32b39d8f8b174e3228"
  },
  "created" : "2017-09-18T12:20:54.192Z",
  "editor" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "ad82ccfcea204da682ccfcea204da678"
  },
  "edited" : "2017-09-18T12:20:54.192Z",
  "name" : "New project name",
  "rootNode" : {
    "uuid" : "984c60480ae241a38c60480ae2a1a3c7"
  },
  "permissions" : {
    "create" : true,
    "read" : true,
    "update" : false,
    "delete" : true,
    "publish" : false,
    "readPublished" : false
  }
}

Node

Content items in Gentics Mesh are called nodes and represent the main structural building blocks for your content. A node is a specific piece of content within your project. The type of a node is always defined by the assigned schema. For example, in a product catalogue website you would create content types like product, product categories, product images, and product manuals.

In Gentics Mesh every content item is a node, there is no separate concept for media assets such as images, videos, and documents. Instead content types for them can be defined individually giving you the freedom to store any metadata with your assets. For your convenience Gentics Mesh is shipped with four default schemas - image, video, audio and document to be customized to your needs and liking!

Nodes can be hierarchically structured if the schema is allowing this. They can be tagged by any number of tags. Furthermore, nodes can be translated into other languages, thus supporting multiple locales.

It is important to understand that a node is just a container for language variants. These language variants will store the actual fields. You can query individual language variants by appending the ?lang query parameter. The language json property within an update or create request will be used to identify which language variant should be created or updated.

API endpoints

Description API endpoint

Create a new node

POST /api/v1/projectName/nodes

Get all nodes of a project

GET /api/v1/projectName/nodes

Get a node

GET /api/v1/:projectName/nodes/:nodeUuid

Update a node

POST /api/v1/:projectName/nodes/:nodeUuid

Delete a node

DELETE /api/v1/:projectName/nodes/:nodeUuid

Update an image, video, or document

POST /api/v1/:projectName/nodes/:nodeUuid/binary/:fieldName

Get an image, video, or document - Crop & resize images

GET /api/v1/:projectName/nodes/:nodeUuid/binary/:fieldName

Crop & resize and update an image

POST /api/v1/:projectName/nodes/:nodeUuid/binaryTransform/:fieldName

Get all child nodes

GET /api/v1/:projectName/nodes/:nodeUuid/children

Delete the language specific content of a node

DELETE /api/v1/:projectName/nodes/:nodeUuid/language/:language

Get the publish status for the given language of a node

GET /api/v1/:projectName/nodes/:nodeUuid/language/:language/published

Move a node

POST /api/v1/:projectName/nodes/:nodeUuid/moveTo/:toUuid

Get a navigation object

GET /api/v1/:projectName/nodes/:nodeUuid/navigation

Get the published status of a node

GET /api/v1/:projectName/nodes/:nodeUuid/published

Publish a node

POST /api/v1/:projectName/nodes/:nodeUuid/published

Unpublish a node

DELETE /api/v1/:projectName/nodes/:nodeUuid/published

Get the tag list of a node

GET /api/v1/:projectName/nodes/:nodeUuid/tags

Update the tag list of a node

POST /api/v1/:projectName/nodes/:nodeUuid/tags

Tag a node

POST /api/v1/:projectName/nodes/:nodeUuid/tags/:tagUuid

Remove a tag from a node

DELETE /api/v1/:projectName/nodes/:nodeUuid/tags/:tagUuid

Response Sample

{
  "uuid" : "6b9d8dafb1cb4f7a9d8dafb1cb1f7ab1",
  "creator" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "f7d1142ea79147be91142ea79177be4e"
  },
  "created" : "2017-09-18T12:20:54.364Z",
  "editor" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "1e369196028a4050b69196028a205011"
  },
  "edited" : "2017-09-18T12:20:54.364Z",
  "parentNode" : {
    "uuid" : "700d0404003c47568d0404003cf756db",
    "displayName" : "parentNodeDisplayName"
  },
  "tags" : [ {
    "name" : "red",
    "uuid" : "a77bd6274a554d1fbbd6274a550d1fd1",
    "tagFamily" : "colors"
  }, {
    "name" : "green",
    "uuid" : "1d73853a21574efab3853a21579efae8",
    "tagFamily" : "colors"
  }, {
    "name" : "car",
    "uuid" : "4ef78bbef8014516b78bbef801251675",
    "tagFamily" : "vehicles"
  }, {
    "name" : "ship",
    "uuid" : "ed47fc909db6418587fc909db6e185ee",
    "tagFamily" : "vehicles"
  } ],
  "childrenInfo" : { },
  "schema" : {
    "name" : "content",
    "uuid" : "cffbacbb5dc04085bbacbb5dc0b085be",
    "version" : "1.0"
  },
  "container" : false,
  "fields" : {
    "name" : "Name for language tag en",
    "filename" : "dummy-content.en.html",
    "teaser" : "Dummy teaser for en",
    "content" : "Content for language tag en"
  },
  "breadcrumb" : [ {
    "uuid" : "4ec05742b4404cb9805742b4401cb9c0",
    "displayName" : "news",
    "path" : "/news"
  }, {
    "uuid" : "0152d2befd1a4a6892d2befd1a8a6834",
    "displayName" : "2015",
    "path" : "/news/2015"
  } ],
  "permissions" : {
    "create" : true,
    "read" : true,
    "update" : false,
    "delete" : false,
    "publish" : false,
    "readPublished" : false
  }
}

Schema

Typically, each project will require a set of different content types. Together they can be considered the content model of your project. Staying with the example of a product catalogue website: a product, product category, product image, and product manual each represent a separate content type. In Gentics Mesh, a schema is used to define such content types in terms of a couple of standard fields (e.g. uuid, name, description, version, etc.) and an arbitrary number of custom fields. Available field types are string, number, HTML, date, binary, list, node, micronode, boolean. You can think of a schema as a blueprint for new content items.

Using the container property, a schema can be configured to allow for hierarchically structuring nodes. Nodes based on a such a schema may contain child nodes. This is the basis for building content trees in Gentics Mesh and leveraging the power of automatic navigation menus, breadcrumbs and pretty URLs.

API endpoints

Description API endpoint

Create a schema

POST /api/v1/schemas/

Get all schemas

GET /api/v1/schemas/

Get a schema

GET /api/v1/schemas/:schemaUuid

Update a schema

POST /api/v1/schemas/:schemaUuid

Delete a schema

DELETE /api/v1/schema/:schemaUuid

Create a changeset for migrating a schema and all affected nodes

POST /api/v1/schema/:schemaUuid/diff

Migrate a schema and all affected nodes with a set of changes

POST /api/v1/schema/:schemaUuid/changes

Response Sample

{
  "uuid" : "bd939764201a4713939764201ae713bb",
  "displayField" : "name",
  "segmentField" : "name",
  "container" : false,
  "description" : "Example schema description",
  "name" : "ExampleSchema",
  "fields" : [ {
    "name" : "name",
    "label" : "Name",
    "required" : false,
    "type" : "string"
  }, {
    "name" : "number",
    "label" : "Number",
    "required" : false,
    "type" : "number"
  }, {
    "name" : "html",
    "label" : "Teaser",
    "required" : false,
    "type" : "html"
  }, {
    "name" : "list",
    "label" : "List of nodes",
    "required" : false,
    "listType" : "node",
    "type" : "list",
    "allow" : [ "content", "video" ]
  }, {
    "name" : "node",
    "required" : false,
    "type" : "node",
    "allow" : [ "content", "video", "image" ]
  }, {
    "name" : "location",
    "label" : "Location",
    "required" : false,
    "type" : "micronode",
    "allow" : [ "geolocation" ]
  }, {
    "name" : "locationlist",
    "label" : "List of Locations",
    "required" : false,
    "listType" : "micronode",
    "type" : "list",
    "allow" : [ "geolocation" ]
  } ],
  "permissions" : {
    "create" : true,
    "read" : true,
    "update" : true,
    "delete" : true,
    "publish" : false,
    "readPublished" : false
  }
}

Schema Field

Gentics Mesh allows you to define custom content types with a set of schema fields. A field is defined by an object which must have the following properties:

  • name A unique name to identify the field.

  • type The type of data to be stored in this field.

The following optional properties may be applied to any type of field:

  • required If true, this field may not be left empty.

  • label A human-readable label for the field to be used as a form label in the Gentics Mesh User Interface. If not defined, the name field would be used.

  • searchIndex The search index options of the field. These options can be used to influence how the field information is added to the search index.

There are the following search options:

  • addRaw By default no raw property will be added to the search index. The raw property is useful for term queries which are used to find the exact term specified in the query. Please note that values which exceed 32KB in size will automatically be truncated to be indexable.

In addition to the above, certain types expose additional properties with which to configure the field. Such additional properties are defined in the Schema Field Types section.

Schema Field Types

Typical example for a string schema field:

{
    "name" : "name",
    "label" : "Name",
    "required" : true,
    "type" : "string",
    "allow": ["red", "green", "blue"],
    "searchIndex": {
        "addRaw": true
    }
}
Type Key Description Validations

string

A string field type is used for textual content, like title, names or paragraphs of text.

The required property indicates if the field is mandatory or not.

The optional allow property acts as a whitelist for allowed field values.

number

The number field type is used for whole and decimal numbers.

The required property indicates if the field is mandatory or not.

The optional min property specifies the lowest permitted value.

The optional max property represents the greatest permitted value.

The optional step property allows specifying the size of the permitted increment in value.

date

The date field type stores a date as ISO8601 formatted date string.

The required property indicates if the field is mandatory or not.

boolean

The boolean field type doesn’t have any specific configuration settings.

The required property indicates if the field is mandatory or not.

html

The html field type stores HTML data.

The required property indicates if the field is mandatory or not.

micronode

A micronode field type stores a single micronode. A micronode is similar to a node. Typically they do not exist on their own but are tied to their (parent) node, e.g. an image with caption to be used in a blogpost node. For a detailed description see our definition of Micronode & Microschema.

The required property indicates if the field is mandatory or not.

A micronode field type must have an allow property that acts as a whitelist for allowed microschemas. If allow is an empty array, any type of micronode may be used.

node

A node field type is used to specify a structural relationship between nodes. This kind of reference represents a 1:1 relationship.

The required property indicates if the field is mandatory or not.

A node field type must have an allow property, which acts as a whitelist for schemas which may be used. If allow is an empty array, any type of node may be used.

list

A list field type allows for specifying a list with elements on the basis of other field types and thus represents a powerful mechanism for building your content model:

(1) Within a node you can have simple lists of arbitrary length. The listType property then has to be of type string, number, date, boolean, or HTML. E.g. handling your recipe nodes of your food blog will be a breeze with string-typed lists for ingredients.

(2) You can unleash the power of micronodes, by specifying a list with the listType property set to micronode, and the allow property set to the allowed microschemas. For example, besides having title, teaser, date and author fields, your blogpost schema could define a content field of type list allowing to insert any of your microschemas (e.g. YouTube Video, Image, Text, Galleries, Google Maps, etc.).

(3) Furthermore, a list field type can be used to specify a structural relationship between nodes. In this case, the listType property has to be of type node. This kind of reference represents a 1:n relationship. E.g., in your movie database app, you might want to list all actors of a movie.

The required property indicates if the field is mandatory or not.

A micronode/node listType must have an allow property, which acts as a whitelist for microschemas/schemas which may be used. If allow is an empty array, any type of node may be used.

binary

The binary field type is used to store binary data, e.g., image, video, audio and documents. Depending on the actual data, Gentics Mesh will store related meta data e.g., fileName, fileSize, mimeType, sha512sum and for images specifically width, height, and dominantColor. Gentics Mesh will set values for all meta data properties automatically when uploading an image. The meta data properties mimeType, dominantColor and fileName can be changed on subsequent update requests.

The required property indicates if the field is mandatory or not.

Micronode & Microschema

A micronode is similar to a node. It also follows a schema - a microschema. It is bound to a node and thus is not directly accessible from within the project node tree structure.

With micronodes it is possible to build complex object data structures as they are basically representing subnodes of nodes.

Typical use cases for micronodes are content items that do not exist on their own but are tied to their (parent) node, e.g., media elements of your blogpost such as YouTube videos, image galleries, Google maps, image with caption, vcards, quotes, text paragraphs. As another example consider a recipe having a list of ingredients which in turn consist of a name and a quantity.

Nodes can contain micronodes. Micronodes, however, can not contain further micronodes, thus limiting the nesting level to one.

API endpoints

Description API endpoint

Create a microschema

POST /api/v1/microschemas/

Get all microschemas

GET /api/v1/microschemas/

Get a microschema

GET /api/v1/microschemas/:microschemaUuid

Update a microschema

POST /api/v1/microschemas/:microschemaUuid

Delete a microschema

DELETE /api/v1/microschemas/:microschemaUuid

Create a changeset for migrating a microschema and all affected nodes

POST /api/v1/microschemas/:microschemaUuid/diff

Migrate a microschema and all affected nodes with a set of changes

POST /api/v1/microschemas/:microschemaUuid/changes

Properties

Microschemas share the same properties as schemas except for the properties displayField, container, and segmentField, which are not available in a microschema.

Schema Field Types

In comparison to nodes, micronodes can be built with schema field types String, Number, Date, Boolean, HTML, Node, and Lists.

Fields of type list in micronodes can be of type: String, Number, Date, Boolean, HTML, and Node.

Example

Tag

Gentics Mesh allows tagging of nodes. Tags can not be hierarchically structured.

API endpoints

Description API endpoint

Get the tag list of a node

GET /api/v1/:projectName/nodes/:nodeUuid/tags

Update the tag list of a node

POST /api/v1/:projectName/nodes/:nodeUuid/tags

Tag a node

POST /api/v1/:projectName/nodes/:nodeUuid/tags/:tagUuid

Remove a tag from a node

DELETE /api/v1/:projectName/nodes/:nodeUuid/tags/:tagUuid

Response Sample

{
  "uuid" : "289cb19f764d42b79cb19f764da2b76a",
  "creator" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "128f1135de4446a88f1135de4426a8b4"
  },
  "created" : "2017-09-18T12:20:54.472Z",
  "editor" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "3dd3376845504fa193376845501fa1fd"
  },
  "edited" : "2017-09-18T12:20:54.472Z",
  "tagFamily" : {
    "name" : "colors",
    "uuid" : "0db6b2afa44a4044b6b2afa44ac04486"
  },
  "name" : "Red",
  "permissions" : {
    "create" : true,
    "read" : true,
    "update" : true,
    "delete" : true,
    "publish" : false,
    "readPublished" : false
  }
}

Tag Family

Tags that semantically belong together are grouped in a tag family, allowing to handle disambiguation.

Example tags and tag families:

Tag Family Tags

Fruit

Apple, Pear, Orange

Company

Apple, Microsoft, Google, Amazon

A tag family is defined as part of a project. Tag families can’t be nested.

Response Sample

{
  "creator" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "e6ccbfbbb5394cdc8cbfbbb5398cdcd3"
  },
  "created" : "2017-09-18T12:20:54.471Z",
  "editor" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "821c951d901744039c951d9017d403ff"
  },
  "edited" : "2017-09-18T12:20:54.471Z",
  "name" : "Nicer colors",
  "permissions" : {
    "create" : true,
    "read" : true,
    "update" : false,
    "delete" : true,
    "publish" : false,
    "readPublished" : false
  }
}

User

Gentics Mesh users can be physical persons or client apps interacting with elements in Gentics Mesh. Both have a user object counterpart in Gentics Mesh. This user object has a standard set of properties, e.g.firstname, lastname, username, and emailAddress , which can be extended by referencing a custom user object.

Gentics Mesh supports user management for your apps! The property nodeReference is used for storing additional user-related data based on a schema you define, thus allowing for extensible user profiles.

In order to be able to store and retrieve content, a user needs to authenticate using one of the available authentication mechanisms.

API endpoints

Description API endpoint

Get all users

GET /api/v1/users/

Create a user

POST /api/v1/users/

Get a user

GET /api/v1/users/:userUuid

Update a user

POST /api/v1/users/:userUuid

Deactivate a user

DELETE /api/v1/users/:userUuid

Read user permissions on elements

GET /api/v1/users/:userUuid/permissions/:path

Return a one time token to update a user

POST /api/v1/users/:userUuid/reset_token

Return an API token

POST /api/v1/users/:userUuid/token

Invalidate an API token

DELETE /api/v1/users/:userUuid/token

Response Sample

{
  "uuid" : "8ca7c72cd1e74916a7c72cd1e7d916ed",
  "creator" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "42aed4d5e43b4a01aed4d5e43b7a0157"
  },
  "created" : "2017-09-18T12:20:54.133Z",
  "editor" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "0b5cb9d74e3e4bad9cb9d74e3e1badd9"
  },
  "edited" : "2017-09-18T12:20:54.133Z",
  "lastname" : "Doe",
  "firstname" : "Joe",
  "username" : "jdoe",
  "emailAddress" : "j.doe@nowhere.com",
  "nodeReference" : {
    "projectName" : "dummy",
    "uuid" : "33004caa75e44366804caa75e4c366dc"
  },
  "enabled" : true,
  "groups" : [ {
    "name" : "editors",
    "uuid" : "8634019e61614eadb4019e61619ead42"
  } ],
  "permissions" : {
    "create" : true,
    "read" : true,
    "update" : true,
    "delete" : true,
    "publish" : false,
    "readPublished" : false
  }
}

Group

Groups are used to organize users and efficiently grant them permissions by assigning relevant roles to groups. Groups ca not be nested. Instead, a user can be part of several groups.

API endpoints

Description API endpoint

Get all groups

GET /api/v1/groups/

Create a group

POST /api/v1/groups/

Get a group

GET /api/v1/group/:groupUuid

Update a group

POST /api/v1/group/:groupUuid

Delete a group

DELETE /api/v1/group/:groupUuid

Get all roles assigned to a group

GET /api/v1/group/:groupUuid/roles

Assign a role to a group

POST /api/v1/group/:groupUuid/roles/:rolesUuid

Remove a role from a group

DELETE /api/v1/group/:groupUuid/roles/:rolesUuid

Get all users assigned to a group

GET /api/v1/group/:groupUuid/users

Add user to a group

POST /api/v1/group/:groupUuid/users/:userUuid

Remove user from a group

DELETE /api/v1/group/:groupUuid/users/:userUuid

Response Sample

{
  "uuid" : "059a275ac83847b59a275ac83887b5d9",
  "creator" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "f21c17027b4c41d19c17027b4cd1d14a"
  },
  "created" : "2017-09-18T12:20:54.174Z",
  "editor" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "78315bc855204c25b15bc855202c2562"
  },
  "edited" : "2017-09-18T12:20:54.174Z",
  "name" : "New group name",
  "roles" : [ {
    "name" : "admin",
    "uuid" : "4081f0c1a36d4bd781f0c1a36d8bd7c5"
  } ],
  "permissions" : {
    "create" : true,
    "read" : true,
    "update" : true,
    "delete" : true,
    "publish" : false,
    "readPublished" : false
  }
}

Role

Roles are used to manage permissions between the role and other elements in Gentics Mesh (i.e., nodes, schemas, users, roles, etc.). Roles can be assigned to groups. Thus, a user of a group with roles inherits the permissions that are bound to these roles. Roles can’t be nested.

API endpoints

Description API endpoint

Get all roles

GET /api/v1/roles/

Create a role

POST /api/v1/roles/

Get a role

GET /api/v1/roles/:roleUuid

Update a role

POST /api/v1/roles/:roleUuid

Delete a role

DELETE /api/v1/roles/:roleUuid

Read role permissions on elements

GET /api/v1/roles/:roleUuid/permissions/:path

Set role permissions on elements

POST /api/v1/roles/:roleUuid/permissions/:path

Response Sample

{
  "uuid" : "9f7af0b8bbec477dbaf0b8bbecb77da3",
  "creator" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "5954da42c322402a94da42c322602a3a"
  },
  "created" : "2017-09-18T12:20:54.156Z",
  "editor" : {
    "firstName" : "Joe",
    "lastName" : "Doe",
    "uuid" : "1b2ce06c71754070ace06c71755070a1"
  },
  "edited" : "2017-09-18T12:20:54.156Z",
  "name" : "New role name",
  "groups" : [ ],
  "permissions" : {
    "create" : true,
    "read" : true,
    "update" : true,
    "delete" : true,
    "publish" : false,
    "readPublished" : false
  }
}