This documentation provides information on the structure and functionality of the Gentics Mesh server and its API endpoints.

TL;DR

Gentics Mesh is a API-Centric CMS Server written in Java which enables you to store and retrieve JSON documents and binaries via REST. Gentics Mesh will also provide you a lot of powerful tools build around and for those documents.

  • Document level permission system

  • Search API

  • GraphQL API

  • Webroot API for easy integration with modern routing frameworks

  • Image Manipulation API

  • Tagging system

  • Schema system for documents

  • Clustering (in development)

  • Versioning of your documents

REST API

The Gentics Mesh REST API provides endpoints which enable you to invoke CRUD operations on any Gentics Mesh element. There are many things you can do with the REST API. For example:

  • You can create new users.

  • You can create nodes and tag them with tags.

  • Binary data can be added to nodes.

  • You can find nodes which match your search parameters.

All REST API responses are only available in JSON.

The Postman chrome extension can be used to build and invoke requests from your browser to Gentics Mesh.

Authentication

Overview

Gentics Mesh provides multiple ways of authentication:

  • Authentication via login

  • Authentication via API token

  • No authentication - Access via anonymous user

Sending user credentials as base64 encoded string, or as plaintext is highly insecure to be used on an open network. This method MUST not be used in scenarios other than debugging and development when the connection between server and client is trusted.
Authentication Configuration

Gentics Mesh uses JWT (JSON Web Token) to handle authentication. It is thus required to create a cryptograph key to sign the sign and verify the generated JWT’s. Typically, if no keystore file has been provided, Gentics Mesh will create one on the basis of the configuration details in mesh.yml. If the keystorePassword property is omitted, a password will be generated randomly and stored in the configuration file.

It can be configured within the mesh.yml configuration file.

security:
  tokenExpirationTime: 3600
  keystorePassword: "secret"
  keystorePath: "keystore.jceks"
  algorithm: "HS256"

Alternatively, you can use the Java keytool to create a new keystore. Here is an example on how to create a keystore which contains a HMacSHA256 key:

keytool -genseckey -keystore keystore.jceks -storetype jceks -storepass secret -keyalg HMacSHA256 -keysize 2048 -alias HS256 -keypass secret

After creating the keystore, you need to set the keystore password, the path to the keystore file, and the used algorithm in the mesh.yml configuration file.

JWT

In order to be able to store and retrieve content, a Gentics Mesh user needs to authenticate (username:password).

Each way will store a JWT in a cookie which is used to authenticate the user for succeeding requests. The token only lasts a certain amount of time (which can be configured in the mesh.yml file), so it might be necessary to refresh the token. The JWT will be automatically renewed with every request on the Gentics Mesh API.

Currently, all data including media assets such as images, videos, and documents are secured and need authentication to be retrieved.

Login

Basic Authentication Header

In basic authentication, when a client requests a URL that requires authentication, the server requests the client to authenticate itself by sending a 401-Not Authorized code. The client, in return, answers with login credentials sent in the authorization header:

authorization: Basic {base64_encode(username:password)}

In Gentics Mesh, a user can be authenticated by invoking a regular GET request to the /api/v1/auth/login end point including a basic authentication HTTP header.

Example:

curl -v -X GET   http://localhost:8080/api/v1/auth/login   -H 'authorization: Basic YWRtaW46YWRtaW4='

The response will be a valid JWT as well as set a cookie with the token.

{
  "token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzczMDYzLCJleHAiOjE0OTE3NzY2NjN9.8iG3I0Pe1M7J43pwbsBXiBOd6p0sn9dRxO3NfazVbOk="
}
POST JSON Data

Alternatively, the user can POST his or her credentials to the /api/v1/auth/login end point in order to retrieve a token. The JSON object must contain these fields:

  • username The username of the user

  • password The password of the user

If the authentication was successful, the server will respond with a JSON object containing a single property:

  • token The token to be sent on every subsequent request.

Additionally, the token will also be provided in a cookie.

Example:

curl -v -X POST \
  http://localhost:8080/api/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{
  "username" : "admin",
  "password" : "admin"
}'
*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8080 (#0)
> POST /api/v1/auth/login HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.50.3
> Accept: */*
> content-type: application/json
> Content-Length: 50
>
* upload completely sent off: 50 out of 50 bytes
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Cache-Control: no-cache
< Content-Length: 208
< Set-Cookie: mesh.token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzczODU0LCJleHAiOjE0OTE3Nzc0NTR9._qt3Eufi7-3jnvgQ8lfe_KwJbd5ePwx5jOFrCK9w76A=; Max-Age=3600; Expires=Sun, 9 Apr 2017 22:37:34 GMT; Path=/
<
{
  "token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzczODU0LCJleHAiOjE0OTE3Nzc0NTR9._qt3Eufi7-3jnvgQ8lfe_KwJbd5ePwx5jOFrCK9w76A="
* Curl_http_done: called premature == 0
* Connection #0 to host localhost left intact
}

All the login method will yield a JSON web token. To make this easy mesh will directly set this token within a cookie.

The JWT can be provided in two ways. By default it is passed along with a cookie value. This is useful for embedding binary image nodes directly in HTML, since the browser will automatically handle authentication on the basis of the cookie. Alternatively, the token can be passed along within the Authorization header which includes the regular JWT Bearer <Token>, where <Token> is the token you received from the login/cookie.

curl -X GET \
  http://localhost:8080/api/v1/demo/nodes \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzY1NDEzLCJleHAiOjE0OTE3NjkwMTN9.UY8OgjiK5qyZobAWt6X1Vd1Z-zg68BeJgGZKbW4Ucj0=' \

API token

An API token can be used to authenticate an user. The API token will never expire. This is different from regular tokens which will be issued when calling /api/v1/auth/login. Leaking an API token is potentially dangerous and thus the API token should only be used in combination with a secure connection.

Typical usecases are backend implementations which constantly communicate with Gentics Mesh via a secure / local connection.

The token can be issued on a user basis via POST /api/v1/users/:userUuid/token.

Creating a new API token will automatically invalidate the previously issued token.

Since the token is just a regular JWT you just need to add it to your request Authorization header field.

curl -X GET \
  http://localhost:8080/api/v1/demo/nodes \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzY1NDEzLCJleHAiOjE0OTE3NjkwMTN9.UY8OgjiK5qyZobAWt6X1Vd1Z-zg68BeJgGZKbW4Ucj0=' \

It is possible to manually revoke the issued token via DELETE /api/v1/users/:userUuid/token. Once the token is invalidated it can no longer be used for authentication.

Anonymous Access

Sometimes it may be desirable to serve public content via Gentics Mesh. All Gentics Mesh instances ship with a included anonymous user/role/group set. Requests to Gentics Mesh which are not authenticated will automatically use the user with the username anonymous to authenticate and check the needed permissions.

You can assign read permissions to the anonymous role for all elements you want to be public.

Assigning other permissions or adding existing roles would of course allow for other operations to be granted.

It is possible to disable this feature by deleting the anonymous user and disabling the enableAnonymousAccess flag in the security section of the mesh.yml file.

Recreating the anonymous user would automatically re-enable the feature if the configuration setting enableAnonymousAccess is set to true.

Encoding

Gentics Mesh expects and returns UTF-8 encoded data. Sending data in any other encoding format will result in encoding issues.

Headers

It is important to set the Content-Type: application/json when sending JSON data and to also set the Accept header in order to signal Gentics Mesh that your client is accepting JSON.

Content-Type: application/json
Accept: application/json

A request which is not well formatted may fail. Gentics Mesh will do its best to identify the issue and return a meaningful error response in those cases.

Paging

The paging query parameters are perPage and page . It is important to note that page is 1-based and perPage can be set to 0 in order to just retrieve a count of elements.

File Upload

Binary data can be attached to node binary fields which have been created using a schema that lists one or more binary fields. The /api/v1/nodes/:uuid/binary/:fieldName endpoint can be used to POST binary data and thus update the stored binary field. This endpoint is accepting only multipart/form-data . It is required to specify the version and language within the update request. This is similar to regular node update requests in which these information must be added to the JSON.

----------Geg2Oob
Content-Disposition: form-data; name="version"

1.0

----------Geg2Oob
Content-Disposition: form-data; name="language"

en

----------Geg2Oob
Content-Disposition: form-data; name="shohY6d"; filename="somefile.bin"
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary

fileData

----------Geg2Oob--

Examples

Create a new node

It is mandatory to specify the parentNode reference, language and schema field when creating a node. It is possible specify the schema uuid instead of the name. At least one property within the schema object must be set.

POST /api/v1/demo/nodes HTTP/1.1
Host: localhost:8080
Cookie: mesh.session=61ac7969-e5ad-4c28-bc0f-0869a04e4db1
Content-Type: application/json
Accept: application/json

{
  "language" : "en",
  "fields" : {
    "name" : "DeLorean DMC-12",
    "description" : "The DeLorean DMC-12 is a sports car manufactured by John DeLorean's DeLorean Motor Company for the American market from 1981–83."
  },
  "parentNode" : {
    "uuid" : "daec8d567d144629ac8d567d14d629aa"
  },
  "schema" : {
    "name" : "vehicle"
  }
}

Update an existing node

The created node can be updated via a PUT request. You may only include those field which should be updated.

PUT /api/v1/demo/nodes/5af8d0e077e34361b8d0e077e353619e HTTP/1.1
Host: localhost:8080
Cookie: mesh.session=61ac7969-e5ad-4c28-bc0f-0869a04e4db1
Content-Type: application/json
Accept: application/json

{
  "language" : "en",
  "fields" : {
    "filename" : "index-renamed.en.html",
    "relatedProduct-" : {
      "uuid" : "09387d86cdcc4563b87d86cdccd563b0"
    },
    "price" : 100.1,
    "enabled" : true,
    "release" : "2017-04-28T13:29:11.022Z",
    "categories" : [ {
      "uuid" : "1edd5113f5a94bcd9d5113f5a9bbcd4c"
    }, {
      "uuid" : "874cb9a481534fd08cb9a481539fd0e4"
    }, {
      "uuid" : "50b2c111198d48c7b2c111198d38c735"
    } ],
    "names" : [ "Jack", "Joe", "Mary", "Tom" ],
    "categoryIds" : [ 1, 42, 133, 7 ],
    "location" : {
      "uuid" : "e4f063dbcbc9404db063dbcbc9604d05",
      "microschema" : {
        "name" : "geolocation",
        "uuid" : "3c7ea33487a542f2bea33487a592f2f6"
      },
      "fields" : {
        "latitude" : 48.208330230278,
        "longitude" : 16.373063840833
      }
    },
    "locations" : [ {
      "uuid" : "522a727b9dd94683aa727b9dd9068319",
      "microschema" : {
        "name" : "geolocation",
        "uuid" : "340ce5b8e3d6496c8ce5b8e3d6b96c29"
      },
      "fields" : {
        "latitude" : 48.208330230278,
        "longitude" : 16.373063840833
      }
    }, {
      "uuid" : "3709fead9a9d411489fead9a9d1114bc",
      "microschema" : {
        "name" : "geolocation",
        "uuid" : "0a7c3d7bda5c41bebc3d7bda5cc1bec3"
      },
      "fields" : {
        "latitude" : 48.137222,
        "longitude" : 11.575556
      }
    } ]
  }
}

Add a tag to a node

Tagging nodes requires just a simple PUT request.

PUT /api/v1/demo/nodes/5af8d0e077e34361b8d0e077e353619e/tags/ba2edcdb1234489daedcdb1234289d38 HTTP/1.1
Host: localhost:8080
Cookie: mesh.session=61ac7969-e5ad-4c28-bc0f-0869a04e4db1
Accept: application/json

Software Stack

Component Type Version

OrientDB

Graph Database

2.2.x

Ferma

OGM

2.2.x

Elasticsearch

Search Engine

2.3.x

Vert.x

Core Framework

3.3.x

Hazelcast

In-Memory Data Grid

3.5.x

https://google.github.io/dagger/

Dependency Injection

2.6.x

Installation

There is no dedicated installation procedure for Gentics Mesh. You just download the mesh jar file and start it using Java.

Oracle Java Runtime 1.8.0_40 or newer is required to run Gentics Mesh.

java -jar mesh-demo-0.9.0.jar

Docker

Alternatively you can start mesh using docker via:

The mesh-demo image contains mesh which provides the demo data and demo application.

docker run -p 8080:8080 gentics/mesh-demo
or
docker run -v /opt/data/:/mesh/data -p 8080:8080 gentics/mesh-demo

The mesh image contains an empty Gentics Mesh server without any demo content.

docker run -p 8080:8080 gentics/mesh
or
docker run -v /opt/data/:/mesh/data -p 8080:8080 gentics/mesh

System Requirements

  • Oracle Java Runtime (JRE) 8u60+

System Configuration

The max open file limit on Linux has to be raised on most Linux systems since the embedded graph database and elasticsearch server often exceed the amount of concurrent open files.

Edit /etc/security/limits.conf and add these two lines:

Mesh   soft    nofile  60000
Mesh   hard    nofile  60000

Edit /etc/pam.d/su and uncomment or add the following line:

session    required   pam_limits.so

Please note that this change may require a logout and login after it is being applied.

Settings

The main mesh.yml configuration file contains various settings to configure the graph database and various file system paths.

Unresolved directive in index.asciidoc - include::examples/mesh-config.yml[]
Configuration Type Description

clusterMode

Flag

The internal hazelcast in-memory data grid will be enabled if this flag is set to true.

updateCheck

Flag

A update check to the mesh update server will be invoked during startup if this flag is set to true.

defaultPageSize

Number

Default page size.

defaultLanguage

String

Default language which is used as a fallback when no language was specified.

verticles

List

List of vert.x java verticle classes which will be loaded during startup.

tempDirectory

Path

Path to the main temporary filesystem directory.

HTTPS/SSL

To enable https you have to specify the server key and the server certificate within the configuration.

You can create a snakeoil certificate for testing purposes this way:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 90 -nodes

Server Options

Configuration Type Description

httpServerOptions.port

Number

Http Port number.

httpServerOptions.ssl

Boolean

Enable or disable SSL support.

httpServerOptions.corsAllowedOriginPattern

RegEx

Regex which will validate the origin CORS header.

httpServerOptions.enableCors

Boolean

Enable CORS support.

httpServerOptions.certPath

Path

SSL certificate path.

httpServerOptions.keyPath

Path

SSL key path.

Storage Options

By default all specified directories are relative to the current working directory.

Configuration Type Description

storageOptions.directory

Path

Path to the graph database storage location.

storageOptions.backupDirectory

Path

Backup directory.

storageOptions.exportDirectory

Path

Export directory.

storageOptions.startServer

Boolean

Flag that indicates whether the graph database server component should be started. By default only an embedded graph database is used which does not start a graph server.

storageOptions.parameters

JSON

Additional JSON parameters that will be passed on to the used graph database implementation.

Upload Options

Configuration Type Description

uploadOptions.byteLimit

Number

Upload limit in bytes.

uploadOptions.directory

Path

Filesystem directory for uploaded binary data.

uploadOptions.tempDirectory

Path

Temporary directory for uploaded binary data. Finished files will be moved to the upload directory.

Cache Options

Gentics Mesh does not manage any cache structure but it is possible to tweak the underlying graph and elasticsearch database cache settings.

Features

Password Recovery

A user who lost his password can recover it using a recovery token. This token can be issued by a user or admin which has permissions to create new users. The /api/v1/users/:userUuid/token endpoint will return a token code which can for example be passed along to an email service which sends a recovery email to the user which includes this token.

The user can use this token to update his user record via /api/v1/users/:userUuid?token=TOKENCODE. This works even if the user is not authenticated. The token will be invalidated once it has been used.

Permissions

Permissions exist between roles and other elements (including other roles). Most responses within Gentics Mesh will contain a list of permissions which may indicate that CRUD operations on the returned element is restricted in a way.

The /api/v1/roles/:roleUuid/permissions endpoint can be used to assign or revoke permissions to/from a role.

This endpoint can also be used to apply recursive permissions. It is important to note that permissions can be applied to individual elements and onto the set of elements which is identified by the endpoint name (e.g: /groups).

For newly created objects CRUD permissions are assigned to those roles that would be able to also create the object in the first place. By this we ensure that roles that would also be able to create the object are now able to invoke CRUD on the newly created object.

Example:

  • User John is assigned to Role A. Role A grants him to create a new child Node in a parent Node.

  • User Mary is assigned to Role B. Role B grants her to also create a new child Node in the same parent Node.

  • When John creates a new Node the permission system identifies Role B as a role that would also be able to create the object. Therefore CRUD permissions are assigned in between Role A and B and the newly created object.

Users

Recursive permission changes on /users will also affect all listed users.

Element Permission Description

/api/v1/users

Create

New users can be created.

/api/v1/users

Read

Not used

/api/v1/users

Update

Not used

/api/v1/users

Delete

Not used

/api/v1/users

Read Published

Not used

/api/v1/users

Publish

Not used

Recursive permission changes on /users/:uuid have no effect on referenced elements such as node references.

Element Permission Description

/api/v1/users/:uuid

Create

Not used

/api/v1/users/:uuid

Read

User can be read.

/api/v1/users/:uuid

Update

User can be updated.

/api/v1/users/:uuid

Delete

User can be deleted.

/api/v1/users/:uuid

Read Published

Not used

/api/v1/users/:uuid

Publish

Not used

Groups

Recursive permission changes on /groups will affect all groups.

Element Permission Description

/api/v1/groups

Create

New roles can be created.

/api/v1/groups

Read

Not used

/api/v1/groups

Update

Not used

/api/v1/groups

Delete

Not used

/api/v1/groups

Read Published

Not used

/api/v1/groups

Publish

Not used

Recursive permission changes on /groups/:uuid will also affect users of the group but not roles that are linked to the group.

Element Permission Description

/api/v1/groups/:uuid

Create

Not used

/api/v1/groups/:uuid

Read

Group can be read.

/api/v1/groups/:uuid

Update

Group can be updated.

/api/v1/groups/:uuid

Delete

Group can be deleted.

/api/v1/groups/:uuid

Read Published

Not used

/api/v1/groups/:uuid

Publish

Not used

Roles

Element Permission Description

/api/v1/roles

Create

New roles can be created.

/api/v1/roles

Read

Not used

/api/v1/roles

Update

Not used

/api/v1/roles

Delete

Not used

/api/v1/roles

Read Published

Not used

/api/v1/roles

Publish

Not used

Recursive permission changes on /roles/:uuid have no effect.

Element Permission Description

/api/v1/roles/:uuid

Create

Not used

/api/v1/roles/:uuid

Read

Role can be read.

/api/v1/roles/:uuid

Update

Role can be updated.

/api/v1/roles/:uuid

Delete

Role can be deleted.

/api/v1/roles/:uuid

Read Published

Not used

/api/v1/roles/:uuid

Publish

Not used

Schemas

Recursive permission changes on /schemas will also affect schemas.

Element Permission Description

/api/v1/schemas

Create

New schemas can be created.

/api/v1/schemas

Read

Not used

/api/v1/schemas

Update

Not used

/api/v1/schemas

Delete

Not used

/api/v1/schemas

Read Published

Not used

/api/v1/schemas

Publish

Not used

Recursive permission changes on /schemas/:uuid have no effect on referenced elements.

Element Permission Description

/api/v1/schemas/:uuid

Create

Not used

/api/v1/schemas/:uuid

Read

The schema can be read. Read permission on the schema is also needed to be able to create new nodes that are based upon the schema.

/api/v1/schemas/:uuid

Update

The schema can be updated.

/api/v1/schemas/:uuid

Delete

The schema can be deleted.

/api/v1/schemas/:uuid

Read Published

Not used

/api/v1/schemas/:uuid

Publish

Not used

Microschemas

Recursive permission changes on /schemas will also affect schemas.

Element Permission Description

/api/v1/microschemas

Create

New microschemas can be created.

/api/v1/microschemas

Read

Not used

/api/v1/microschemas

Update

Not used

/api/v1/microschemas

Delete

Not used

/api/v1/microschemas

Read Published

Not used

/api/v1/microschemas

Publish

Not used

Recursive permission changes on /microschemas/:uuid have no effect on referenced elements.

Element Permission Description

/api/v1/microschemas/:uuid

Create

Not used

/api/v1/microschemas/:uuid

Read

The microschema can be read.

/api/v1/microschemas/:uuid

Update

The microschema can be updated.

/api/v1/microschemas/:uuid

Delete

The microschema can be deleted.

/api/v1/microschemas/:uuid

Read Published

Not used

/api/v1/microschemas/:uuid

Publish

Not used

Projects

Recursive permission changes on /projects will also affect all projects and those elements.

Element Permission Description

/api/v1/projects

Create

Create new projects.

/api/v1/projects

Read

Not used

/api/v1/projects

Update

Not used

/api/v1/projects

Delete

Not used

/api/v1/projects

Read Published

Not used

/api/v1/projects

Publish

Not used

Recursive permission changes on /projects/:uuid will also affect schemas, tagfamilies (and tags), nodes and subnodes.

Element Permission Description

/api/v1/projects/:uuid

Create

Not used

/api/v1/projects/:uuid

Read

Project can be read.

/api/v1/projects/:uuid

Update

Project can be updated.

/api/v1/projects/:uuid

Delete

Project can be deleted.

/api/v1/projects/:uuid

Read Published

Affected node publish versions can be read.

/api/v1/projects/:uuid

Publish

Affected node can be published.

Tag Families

Recursive permission changes on /projects/:uuid/tagFamilies will also all tagfamiles and those tags.

Element Permission Description

/api/v1/projects/:uuid/tagFamilies

Create

Create new tag families.

/api/v1/projects/:uuid/tagFamilies

Read

Not used

/api/v1/projects/:uuid/tagFamilies

Update

Not used

/api/v1/projects/:uuid/tagFamilies

Delete

Not used

/api/v1/projects/:uuid/tagFamilies

Read Published

Not used

/api/v1/projects/:uuid/tagFamilies

Publish

Not used

Recursive permission changes on /projects/:uuid/tagFamilies/:uuid will also affect tags.

Element Permission Description

/api/v1/projects/:uuid/tagFamilies/:uuid

Create

Tags can be created within the tag family.

/api/v1/projects/:uuid/tagFamilies/:uuid

Read

Tag family can be read.

/api/v1/projects/:uuid/tagFamilies/:uuid

Update

Tag family can be updated.

/api/v1/projects/:uuid/tagFamilies/:uuid

Delete

Tag family can be deleted.

/api/v1/projects/:uuid/tagFamilies/:uuid

Read Published

Not used

/api/v1/projects/:uuid/tagFamilies/:uuid

Publish

Not used

Tags

Recursive permission on /api/v1/projects/:uuid/tagFamilies/:uuid/tags changes have no effect.

Element Permission Description

/api/v1/:projectName/tagFamilies/:uuid/tags

Create

Create new tags.

/api/v1/:projectName/tagFamilies/:uuid/tags

Read

Not used

/api/v1/:projectName/tagFamilies/:uuid/tags

Update

Not used

/api/v1/:projectName/tagFamilies/:uuid/tags

Delete

Not used

/api/v1/:projectName/tagFamilies/:uuid/tags

Read Published

Not used

/api/v1/:projectName/tagFamilies/:uuid/tags

Publish

Not used

Recursive permission changes on /projects/:uuid/tagFamilies/:uuid/tags/:uuid have no effect.

Element Permission Description

/api/v1/:projectName/tags/:uuid

Create

Not used

/api/v1/:projectName/tags/:uuid

Read

Tag can be read.

/api/v1/:projectName/tags/:uuid

Update

Tag can be updated.

/api/v1/:projectName/tags/:uuid

Delete

Tag can be deleted.

/api/v1/:projectName/tags/:uuid

Read Published

Not used

/api/v1/:projectName/tags/:uuid

Publish

Not used

Nodes

Recursive permission changes on /:projectName/nodes/:uuid will also affect children of the node.

Element Permission Description

/api/v1/:projectName/nodes

Create

Not used

/api/v1/:projectName/nodes

Read

Not used

/api/v1/:projectName/nodes

Update

Not used

/api/v1/:projectName/nodes

Delete

Not used

/api/v1/:projectName/nodes

Read Published

Not used

/api/v1/:projectName/nodes

Publish

Not used

Recursive permission changes on /:projectName/nodes/:uuid will also affect children of the node.

Element Permission Description

/api/v1/:projectName/nodes/:uuid

Create

Create new nodes within the node

/api/v1/:projectName/nodes/:uuid

Read

Node can be read.

/api/v1/:projectName/nodes/:uuid

Update

Node can be updated.

/api/v1/:projectName/nodes/:uuid

Delete

Node can be deleted.

/api/v1/:projectName/nodes/:uuid

Read Published

Published version can be read.

/api/v1/:projectName/nodes/:uuid

Publish

Node can be published.

Releases

Element Permission Description

/api/v1/:projectName/releases

Create

Releases can be created.

/api/v1/:projectName/releases

Read

Not used

/api/v1/:projectName/releases

Update

Not used

/api/v1/:projectName/releases

Delete

Not used

/api/v1/:projectName/releases

Read Published

Not used

/api/v1/:projectName/releases

Publish

Not used

Element Permission Description

/api/v1/:projectName/releases/:uuid

Create

Nod used

/api/v1/:projectName/releases/:uuid

Read

Release can be read.

/api/v1/:projectName/releases/:uuid

Update

Release can be updated.

/api/v1/:projectName/releases/:uuid

Delete

Permission does not apply. Releases can’t be deleted.

/api/v1/:projectName/releases/:uuid

Read Published

Not used

/api/v1/:projectName/releases/:uuid

Publish

Not used

WebRoot

The /api/v1/:projectName/webroot/:path endpoint can be used to access nodes via a regular web path instead of using uuids.

Example: /api/v1/demo/webroot/Vehicle%20Images/ford-gt.jpg?width=1000

This makes it possible to integrate Gentics Mesh with many known routing frameworks.

Framework Language Example

Silex

PHP

Blogpost

ExpressJS

JS

Blogpost

Vert.x

Java,JS,Ceylon

Blogpost

Lotus

Ruby

-

A webroot path consists of multiple path segments. Each segment of the url must be URL encoded. A list of segments can be provided by a single node. The segmentField information from the schema is used to determine the segment field value which the node provides. Each language of the node must provide different path segment.

The Ford GT Image node for example provides the path segment ford-gt.jpg since the used schema vehicleImage points to the binary field image. The binary field contains the filename ford-gt.jpg.

The segmentField parameter within the schema is therefore used to map in between fields and the path segment.

  • ford-gt.jpg/api/v1/demo/webroot/Vehicle%20Images/ford-gt.jpg

The binary data will be returned if the path targets a node in which the binary fileName property provides the segment. It is possible to differentiate between a binary response and a normal JSON response by checking whether the Content-Disposition header parameter is set. The header value will only be set when binary data is returned.

The router implementation can use this in order to be able to to decide whether to handle the JSON data or whether the binary data should just be passed through to the requester.

Navigations

There are two ways of generating a nested navigation response. You can either use /api/v1/:projectName/nodes/:uuid/navigation or /api/v1/:projectName/navroot/:path endpoints.

Each endpoint will return a navigation response which contains the nested navigation tree structure. The maxDepth parameter may be used to limit the navigation depth (default: 10).

Gentics Mesh will try to resolve any found mesh-link within any text field of a node if the resolveLinks query parameter has been set to either short, medium or full.

Example: {{mesh.link("2f2de9297c8143e8ade9297c8193e8fc", "en")}} will be transformed into /api/v1/demo/webroot/Vehicle%20Images/ford-gt.jpg when using the ?resolveLinks=full

Valid Links:

  • {{mesh.link("2f2de9297c8143e8ade9297c8193e8fc", "en")}}

  • {{mesh.link('2f2de9297c8143e8ade9297c8193e8fc', 'en')}}

  • {{mesh.link(\"2f2de9297c8143e8ade9297c8193e8fc\", \"en\")}}

  • {{mesh.link("2f2de9297c8143e8ade9297c8193e8fc")}} (Link to default language)

Resolver

The /api/v1/utilities/linkResolver endpoint can be used to resolve mesh links within the posted text data. This is useful when resolving links for a preview page.

Schema / Microschema Migration

Gentics Mesh provides a changelog like system in order to apply and keep track of schema changes. A schema change may be a single change that adds a new field to the schema or a change which updates the schema properties.

Gentics Mesh supports the following change operations:

Operation: addfield

Properties Description

after

Name of the field after which the new field should be inserted

field

Name of the field that should be added

type

Type of the field

listType

Optional list type

{
  "operation" : "ADDFIELD",
  "properties" : {
    "field" : "fieldToBeAdded",
    "label" : "Field Label Value",
    "after" : "firstField",
    "type" : "list",
    "listType" : "html"
  }
}

Operation: removefield

Properties Description

field

Name of the field to be removed

{
  "operation" : "REMOVEFIELD",
  "properties" : {
    "field" : "fieldToBeRemoved"
  }
}

Operation: changefieldtype

Properties Description

field

Name of the field to be modified

type

New field type

listType

(Only applies for lists) New list type

{
  "operation" : "CHANGEFIELDTYPE",
  "properties" : {
    "field" : "fieldToBeChanged",
    "type" : "html"
  }
}

Operation: updatefield

Properties Description

field

Field to be updated

label

New field label

{
  "operation" : "UPDATEFIELD",
  "properties" : {
    "field" : "fieldToBeUpdated",
    "name" : "newName"
  }
}

Operation: updateschema

Properties Description

description

New schema description

order

Array of strings that contains the field order

displayFieldname

New displayFieldname value of the schema

segmentFieldname

New segmentFieldname value of the schema

container

New container flag of the schema

{
  "operation" : "UPDATESCHEMA",
  "properties" : {
    "container" : "true",
    "segmentFieldname" : "newSegmentField",
    "displayFieldname" : "newSegmentField",
    "description" : "new description",
    "label" : "new label"
  }
}

Operation: updatemicroschema

Properties Description

description

New microschema description

{
  "operation" : "UPDATEMICROSCHEMA",
  "properties" : {
    "description" : "new description",
    "label" : "new label"
  }
}

Each change may also provide a migration script. The migration script can be used to modify nodes that were affected by the migration.

Typical usecases for migration scripts are for example dynamic field removal or even custom reformatting of field data. It is also possible to split a single field value into values for two new fields.

The /api/v1/schemas/:uuid/diff and /api/v1/microschemas/:uuid/diff endpoints can be used to generate a list of changes by comparing the stored and posted schema.

This list of changes can be modified and posted to /api/v1/schemas/:uuid/changes for schemas or /api/v1/microschemas/:uuid/changes for microschemas. The posted list of changes will be validated and stored when valid. A schema migration process will be started which runs in the background.

The SockJS compliant /api/v1/eventbus endpoint can be used to register to migration specific messages.

Additionally to websocket it is possible to query whether a migration is running via the /api/v1/admin/status/migrations endpoint.

Sending a schema to /api/v1/schemas:uuid using the PUT method will conveniently combine the diff generation and invocation of the schema migration.

Please note that by default conflicting data will be removed and this action can only be avoided by specifying a custom migration script.

Custom Migration Scripts

Sometimes it is desired to overwrite the default migration behaviour.

The following migration script converts the number value from field node.fields[fieldname] into a ISO-8601 date string which is then stored within the node.fields[fieldname] field.

function migrate(node, fieldname, convert) {
    node.fields[fieldname] = new Date(new Date(node.fields[fieldname]).getTime() + 864000).toISOString();
    return node;
}

Migration scripts also allow you to split up a field value into two different fields.

function migrate(node, fieldname, convert) {
    node.fields["fieldA"] = "First field set";
    node.fields["fieldB"] = "Second field set";
    return node;
}

The provided converter can be used to convert in between field types. This converter will be used if no custom migration script was specified.

function migrate(node, fieldname, convert) {
    var stringValue = convert.toString(node.fields[fieldname]);

    // It is important to use the Java.from method to convert the java list object into a number array.
    var numberArray    = Java.from(convert.toNumberList(node.fields[fieldname]));
    var micronodeArray = Java.from(convert.toMicronodeList(node.fields[fieldname]));
    var dateArray      = Java.from(convert.toDateList(node.fields[fieldname]));
    var booleanArray   = Java.from(convert.toBooleanList(node.fields[fieldname]));

    var numberValue    = convert.toNumber(node.fields[fieldname]);
    var nodeValue      = convert.toNode(node.fields[fieldname]);
    var micronodeValue = convert.toMicronode(node.fields[fieldname]);
    var dateValue      = convert.toDate(node.fields[fieldname]);
    var booleanValue   = convert.toBoolean(node.fields[fieldname]);
    var binaryValue    = convert.toBinary(node.fields[fieldname]);

    // Delete the field
    delete node.fields[fieldname];
    return node;
}

Finally the changes can be applied by sending the request to /api/v1/schemas/:uuid/changes.

{
  "changes" : [ {
    "operation" : "ADDFIELD",
    "properties" : {
      "field" : "listFieldToBeAddedField",
      "label" : "Field Label Value",
      "type" : "list",
      "listType" : "html"
    }
  }, {
    "operation" : "CHANGEFIELDTYPE",
    "properties" : {
      "field" : "fieldToBeUpdated",
      "type" : "string"
    }
  }, {
    "operation" : "REMOVEFIELD",
    "properties" : {
      "field" : "fieldToBeRemoved"
    }
  }, {
    "operation" : "UPDATEFIELD",
    "migrationScript" : "function migrate(node, fieldname) {node.fields[fieldname] = new Date(new Date(node.fields[fieldname]).getTime() + 864000).toISOString(); return node;}",
    "properties" : {
      "field" : "fieldToBeUpdated",
      "displayFieldname" : "newDisplayField",
      "label" : "newLabel"
    }
  }, {
    "operation" : "UPDATESCHEMA",
    "properties" : { }
  } ]
}

Versioning

In order to grasp the concept of versioning in Gentics Mesh it is important to remember that Nodes are containers for language variants. The language variant of a node contains the fields and thus stores all the content.

Versioning within Gentics Mesh only applies to language variants and their referenced fields. Other elements such as Users, groups, roles and even Nodes are not versioned.

Various interactions have different effects for versioning in Mesh. Below is a list of actions which involve versioning.

Node Creation

Once a node has been created the initial start version 0.1 will be assigned to its language variant.

Node Updates

Updating a node’s language variant may create version 0.2 of that language variant if changes have been detected within the posted request fields.

  • No Locks and Conflict detection

It is not required to handle locks in Gentics Mesh. Instead it is required to specify the version in the update request which identifies the version on which the update request was based upon. Mesh will check whether new versions have been created in the meanwhile. Long running edit operations or multiple concurrent editors may create additional versions. The detected changes will automatically compared in order to determine whether the current update request causes a conflict with a newer edit request. Mesh will return a response which contains information about the conflict in those cases. Other update operations which do not cause a conflict will be stored and the changed fields will be updated.

The latest version which was created using a update request is called the draft version. Only a single draft version per language exists.

Publishing Nodes

Node language variant can be published and taken offline. This is especially useful if you want to first work on a draft and review it and later publish it. Publishing a just requires a PUT request on /api/v1/:projectName/nodes/:uuid/published which will publish all language variants of the node. It is also possible to just publish specific language variants via /api/v1/:projectName/nodes/:uuid/languages/:languageTag/published. Mesh will automatically create a new major version when publishing a node language variant (e.g.: 1.0, 2.0). The draft reference will also be updated to point to version 1.0. It is also possible to retrieve detailed information about the published status via a GET request on /api/v1/:/nodes/:uuid/published.

Publishing node language variations requires the user to be assigned to a role which provides the publish permission.
{
  "availableLanguages" : {
    "de" : {
      "published" : false,
      "version" : {
        "uuid" : "cb1864f3094d4e729864f3094d2e72f5",
        "number" : "0.4"
      }
    },
    "en" : {
      "published" : true,
      "version" : {
        "uuid" : "b581b88eb7f84b2581b88eb7f8cb25ce",
        "number" : "3.0"
      },
      "publisher" : {
        "firstName" : "Joe",
        "lastName" : "Doe",
        "uuid" : "be3534739e0d40c3b534739e0d60c3db"
      },
      "publishDate" : "2017-04-28T13:29:11.041Z"
    },
    "fr" : {
      "published" : false,
      "version" : {
        "uuid" : "fd22b927d1384310a2b927d138f310e5",
        "number" : "5.2"
      }
    }
  }
}

It is not possible to publish a specific version. Publish always affects the latest draft version of the language variant.

Taking Nodes Offline

Similarly the language variants of a node can be taken offline via a DELETE request on /api/v1/:projectName/nodes/:uuid/published. Taking a node language variant with version 1.0 offline will just change the node’s publish state. Version 1.0 will still be available.

Reading Nodes

It is possible to load older versions by specifying the ?version parameter. Similarly the published version of can also be loaded using the parameter ?version=published or the draft version via ?version=draft.

By default nodes will be loaded using ?version=published. A nodes list thus may not contain your previously created node because it was not yet published.
Reading published nodes requires the user to be assigned to a role which grants the readpublished permission.

Permissions

Permissions are not version specific. Permissions apply to nodes and not to language variants.

Limitations

At the moment it is not possible to delete older versions.

Releases

So far we learned that node language variants can be versioned and published. Additionally Mesh versioning provides a powerful concept we call Releases. A release is very similar to branches in a versioning control system.

Releases can be used to restructure your nodes and change the contents within a specific release without affecting a different release which provides a different structure/content.

Structural references for nodes always contain release information. This applies to parent/child relationship or taggings, publish states of nodes. This way releases are completely isolated from each other.

It is currently not possible to migrate from one release to another. Nodes of releases can’t be automatically merged to other releases.

Typical usecases are:

  • Updating an existing application installation which uses Gentics Mesh to a new version. The new application version requires new schema versions. By creating a release and migrating the nodes to the new release (new schema versions), it is possible to serve content for both application versions. Each application versions chooses the correct release for getting nodes.

  • Schema versions must be assigned to the release. Each project can have multiple releases. An initial release will automatically be created when creating a project.

All operations to nodes can be scoped to a specific release by adding the ?release=name query parameter. If omitted the latest release will be used to execute the operation.

Implementations which use mesh should always reference a specific release. Otherwise the document structure could change without the implementation being aware of these changes.

Creating a Release

A release requires an unique name. Existing nodes within the project will automatically be migrated into the release. Please note the started node migration will be processed asynchronously and thus not all nodes may be directly accessible within the scope of the release.

This migration is different from a schema version migration. The release node migration just takes care of making all nodes from the previous release available in the newly created release. Unlike the schema migration the node migration will not create new language variant versions.

You can use the eventbus bridge or the dedicated /api/v1/admin/status/migrations endpoint to query the migration status. The migrated JSON property within the release response also indicates whether the node migration has been completed.

Note: Migrated nodes will still have the same uuid as before.

Updating a Release

A release can be renamed and new schema/microschema versions can be assigned to it.

Renaming is useful if you want to change your development release to be the current production release.

Assigning schema versions to the release via a PUT request to /api/v1/:projectName/releases/:uuid/schemas will automatically trigger a schema migration of the affected nodes language variants within the release.

[ {
  "name" : "content",
  "uuid" : "348ddffab4bc45998ddffab4bcd599fd",
  "version" : 1
}, {
  "name" : "folder",
  "uuid" : "16d830d1bde5479e9830d1bde5479e0a",
  "version" : 1
}, {
  "name" : "binary-data",
  "uuid" : "6bdd1e39af854b9c9d1e39af851b9c05",
  "version" : 1
} ]

It is also possible to assign microschemas via a PUT request to /api/v1/:projectName/releases/:uuid/microschemas to the release.

[ {
  "name" : "vcard",
  "uuid" : "3b1fd54aa30748dc9fd54aa30748dca9",
  "version" : 2
}, {
  "name" : "geolocation",
  "uuid" : "c40d9beee56946438d9beee5695643f7",
  "version" : 1
} ]

All nodes which reference the release via the updated schema version will automatically be migrated to use the newer schema version. Please note the started schema migration will be processed asynchronously and thus not all node language variants may be directly accessible within the scope of the release.

The migration will create new versions for the affected node language variants.

It is note worthy that updating a schema and thus creating new schema version will not automatically affect the release. Each schema update created a new schema version. This new version must first be assigned to the release.

Deleting a Release

At the moment it is not possible to delete a release.

Moving Nodes

Releases enable Gentics Mesh to setup multiple content project tree structures. Moving nodes can be scoped to a specific release using the ?release request parameter. The project’s initial release will be used to execute the move operation if no release has been selected.

Tagging Nodes

The tag operation is also scoped to a specific release. This way new tags can be assigned to your nodes for a specific release without affecting the taggings of nodes within an older release.

Tags and tag families are not versioned. Deleting a tag will remove the tag from all nodes that previously referenced this tag.
Taggings to nodes are not versioned.

Deleting Nodes

Deleting nodes is also release specific. Deleting a node via DELETE to /api/v1/:projectName/node/:uuid?release=winter2016 will delete the node and all its sub nodes from the winter2016 release. The node will be completely removed from the system if no more language variants are referenced within any release.

It is also possible to just delete a specific language variant via DELETE to /api/v1/:projectName/node/:uuid/languages/en?release=winter2016 from release winter2016.

Updating Nodes

Releases are completely isolated from each other as explained earlier. This also applies to a node’s language variant versions.

Example:

  • Create release summer2016

  • Create node with language variant de at version 1.0 in release summer2016

  • Create release winter2016

  • Update previously created node in release summer2016 and thus create version 1.1

Release summer2016 will reference node language variant 1.1 and winter2016 will still reference version 1.0 since the winder2016 release was created at the specific point of time in which the language variant in release summer2016 was still at version 1.0.

It is currently not possible to migrate 1.1 from summer2016 to winter2016.

Additionally creating new nodes in summer2016 will not be available in release winter2016.

Permissions

Permissions are not release specific.

Eventbus Bridge / Websocket

The /api/v1/eventbus endpoint allows clients to access the eventbus. This may be useful if you want to react on specific events. Currently only schema migration specific events are handled via this endpoint but more will follow.

The endpoint is SockJS compliant. It is also possible to access the websocket directly via: /api/v1/eventbus/websocket.

Eventname Description

mesh.migration

Receive node and micronode migration specific events

Image Manipulation

Images can be resized by appending the image manipulation query parameters on the binary node endpoint:

Endpoint: /api/v1/:projectName/nodes/:uuid/binaryTransform/:fieldname?width=220

It is also possible to use the image manipulation in combination with the webroot endpoint:

Endpoint: /api/v1/:projectName/webroot/:path?width=220

It is mandatory to specify all four crop parameters when cropping an image.

Parameter Description

width

Target image width.

height

Target image height.

cropx

Crop area start x coordinate.

cropy

Crop area start y coordinate.

cropw

Crop area width.

croph

Crop area height.

Language Fallback

Nodes are translated into different languages. Requests for nodes should contain the requested languages (as comma separated list) as query parameter:

Endpoint: /api/v1/:projectName/nodes/:uuid?lang=en,de

If the requested node is available in any of the languages, the response will contain the fields in that language (first language found). Otherwise, the node will still be returned, but without fields.

Search requests are handled by the /api/v1/search or /api/v1/:projectName/search endpoints.

Elasticsearch is used in order to provide the search functionality. This way elasticsearch queries can be posted to the search endpoints.

The JSON format of stored documents within the elasticsearch differ from the JSON format that is returned via regular Gentics Mesh endpoints. Thus it is important to know the elasticsearch document format when building an elasticsearch query. Below is a list of various example documents.

It is not possible to search for specific individual versions. Instead only published and draft versions per release are stored in the search index.

Users

Endpoint: /api/v1/search/users

{
  "uuid" : "5321109f417e4b30a1109f417e2b306f",
  "creator" : {
    "uuid" : "03932ee80fbc4756932ee80fbca756ce"
  },
  "created" : null,
  "editor" : {
    "uuid" : "03932ee80fbc4756932ee80fbca756ce"
  },
  "edited" : null,
  "username" : "joe1",
  "emailaddress" : "joe1@nowhere.tld",
  "firstname" : "Joe",
  "lastname" : "Doe",
  "groups" : {
    "name" : [ "editors", "superEditors" ],
    "uuid" : [ "bd315bbd0df14193b15bbd0df1719319", "1815a61451cd4b5f95a61451cd9b5f87" ]
  }
}

Groups

Endpoint: /api/v1/search/groups

{
  "name" : "adminGroup",
  "uuid" : "bba315712d584be1a315712d58fbe149",
  "creator" : {
    "uuid" : "229cfda1d0b24bd79cfda1d0b26bd75a"
  },
  "created" : null,
  "editor" : {
    "uuid" : "229cfda1d0b24bd79cfda1d0b26bd75a"
  },
  "edited" : null
}

Roles

Endpoint: /api/v1/search/roles

{
  "name" : "adminRole",
  "uuid" : "a861d203cf6e48bba1d203cf6e38bb17",
  "creator" : {
    "uuid" : "d79953672845493c9953672845593c89"
  },
  "created" : null,
  "editor" : {
    "uuid" : "d79953672845493c9953672845593c89"
  },
  "edited" : null
}

Nodes

Endpoint: /api/v1/search/nodes

{
  "uuid" : "04b57890f7984179b57890f798517952",
  "editor" : {
    "uuid" : "0127a1e77f3c45b0a7a1e77f3c25b012"
  },
  "edited" : "1970-01-01T00:00:00Z",
  "creator" : {
    "uuid" : "0127a1e77f3c45b0a7a1e77f3c25b012"
  },
  "created" : "1970-01-01T00:00:00Z",
  "project" : {
    "name" : "dummyProject",
    "uuid" : "1afe55551a8448eabe55551a8478ea01"
  },
  "tags" : {
    "name" : [ "green", "red" ],
    "uuid" : [ "e3764a8caee54f45b64a8caee53f4578", "8ec87212857342018872128573e201ac" ]
  },
  "tagFamilies" : {
    "colors" : {
      "uuid" : "5cf81d3cd5a34376b81d3cd5a3537631",
      "tags" : [ {
        "name" : "green",
        "uuid" : "e3764a8caee54f45b64a8caee53f4578"
      }, {
        "name" : "red",
        "uuid" : "8ec87212857342018872128573e201ac"
      } ]
    }
  },
  "parentNode" : {
    "uuid" : "651fb3ad3ae34da89fb3ad3ae3bda883"
  },
  "language" : "de",
  "schema" : {
    "name" : "content",
    "uuid" : "4b19a6e3dca94d4c99a6e3dca9cd4c23",
    "version" : "0"
  },
  "fields" : {
    "date" : 1493386151,
    "string" : "The name value",
    "htmlList" : [ "some<b>html", "some<b>html", "some<b>html" ],
    "nodeList" : [ "9d7e864058934964be86405893a964d2", "9d7e864058934964be86405893a964d2", "9d7e864058934964be86405893a964d2" ],
    "number" : 0.146,
    "node" : "9d7e864058934964be86405893a964d2",
    "boolean" : true,
    "stringList" : [ "The name value", "The name value", "The name value" ],
    "micronode" : {
      "microschema" : {
        "name" : null,
        "uuid" : null
      },
      "fields-null" : {
        "latitude" : 16.373063840833,
        "longitude" : 16.373063840833
      }
    },
    "html" : "some<b>html",
    "numberList" : [ 0.146, 0.146, 0.146 ],
    "booleanList" : [ "true", "true", "true" ],
    "dateList" : [ 1493386151, 1493386151, 1493386151 ]
  },
  "displayField" : {
    "key" : "string",
    "value" : null
  }
}

Search nodes by schema name

Listed below is an example search query which can be posted to /api/v1/search/nodes in order to find all nodes across all projects which were created using the content schema. The found nodes will be sorted ascending by creator.

{
  "sort" : {
     "created" : { "order" : "asc" }
  },
  "query":{
    "bool" : {
      "must" : {
        "term" : { "schema.name" : "content" }
       }
    }
  }
}

Search nodes by micronode field values

Find all nodes which have a micronode list field (vcardlist) that contain at least one micronode which contains the two string fields (firstName, lastName) with the values ("Joe", "Doe"):

{
  "query": {
    "nested": {
      "path": "fields.vcardlist",
      "query": {
        "bool": {
          "must": [
            {
              "match": {
                "fields.vcardlist.fields.firstName": "Joe"
              }
            },
            {
              "match": {
                "fields.vcardlist.fields.lastName": "Doe"
              }
            }
          ]
        }
      }
    }
  }
}

Projects

Endpoint: /api/v1/search/projects

{
  "name" : "dummyProject",
  "uuid" : "e672b8183a584edcb2b8183a58fedc0d",
  "creator" : {
    "uuid" : "699aa42f805440479aa42f805440476b"
  },
  "created" : null,
  "editor" : {
    "uuid" : "699aa42f805440479aa42f805440476b"
  },
  "edited" : null
}

Tags

Endpoint: /api/v1/search/tags

{
  "name" : "red",
  "uuid" : "26ee8405e4ba4e5bae8405e4ba1e5bf8",
  "creator" : {
    "uuid" : "a81b00caf58c48649b00caf58c3864e9"
  },
  "created" : null,
  "editor" : {
    "uuid" : "a81b00caf58c48649b00caf58c3864e9"
  },
  "edited" : null,
  "tagFamily" : {
    "name" : "colors",
    "uuid" : "c205f92d371c429985f92d371cf29955"
  },
  "project" : {
    "name" : "dummyProject",
    "uuid" : "be39b9ac27984e0eb9b9ac2798be0e48"
  }
}

Tag Families

Endpoint: /api/v1/search/tagFamilies

{
  "name" : "colors",
  "uuid" : "4e43948037db4b4183948037dbfb412b",
  "creator" : {
    "uuid" : "44caf7b9dcc445778af7b9dcc47577bb"
  },
  "created" : null,
  "editor" : {
    "uuid" : "44caf7b9dcc445778af7b9dcc47577bb"
  },
  "edited" : null,
  "tags" : {
    "name" : [ "red", "green" ],
    "uuid" : [ "4fbdf75d2b774eb6bdf75d2b778eb651", "7af060dd7d264842b060dd7d26684225" ]
  },
  "project" : {
    "name" : "dummyProject",
    "uuid" : "d7c93213ed6f4060893213ed6fa06050"
  }
}

Schemas

Endpoint: /api/v1/search/schemas

{
  "name" : "content",
  "description" : "Content schema",
  "uuid" : "03cd27ed07d948f18d27ed07d998f1be",
  "creator" : {
    "uuid" : "3967b97b777c4d7fa7b97b777c4d7ff9"
  },
  "created" : null,
  "editor" : {
    "uuid" : "3967b97b777c4d7fa7b97b777c4d7ff9"
  },
  "edited" : null
}

Microschemas

Endpoint: /api/v1/search/microschemas

{
  "uuid" : "bf52a4f01074440a92a4f01074f40a61",
  "creator" : {
    "uuid" : "ed754dfcf54e492fb54dfcf54e292f40"
  },
  "created" : null,
  "editor" : {
    "uuid" : "ed754dfcf54e492fb54dfcf54e292f40"
  },
  "edited" : null,
  "name" : "geolocation"
}

Clustering

Clustering support is still in development.

It will be possible to use master/master replication for OrientDB. Clustering for the elasticsearch nodes and the vertx event message bus.

Administration UI

The Gentics Mesh Administration UI is an AngularJS single page application which uses the REST API to interface with Gentics Mesh. By default it can be reached via http://localhost:8080/mesh-ui/.

Configuration

The mesh-ui can be configured using the mesh-ui-config.js file.

(function(window, document) {

    /**
     * Settings which can be configured per app instance, without requiring the app be re-built from
     * source.
     */
    var meshUiConfig = {
        // The URL to the Mesh API
        apiUrl: '/api/v1/',

        // The ISO-639-1 code of the default language
        defaultLanguage: 'en',
        // The ISO-639-1 codes of the available languages
        availableLanguages: ['en', 'de'],

        // Provide an array or URLs for previewing nodes, in the following format:
        //
        // ```
        // {
        //   projectName: [
        //     // label: url
        //     { somePreview: 'http://some/url' },
        //     { otherPreview: 'http://someother/url' }
        //  ]
        // }
        // ```
        // When this option is used, a "preview" button will be available
        // in the node editor pane. Click it will POST the node data to the specified URL. The node will be
        // encoded as form data under the key "node", and its value will need to be de-serialized back into JSON
        // (e.g. using JSON.parse()). The "default" key will make the URls available to all projects.
        previewUrls: {
            default: [
                { default: 'https://httpbin.org/post' }
            ]
        },

        // A microschema control is a custom form component which can be used to render a
        // specific microschema, in place of the default form generator. For full documentation, please
        // see the example in `/microschemaControls/example/exampleControl.js`
        //
        // The `microschemaControlsLocation` may point to any location on the current server or even on
        // another server. Note that if serving microschema controls from a different server or port, you
        // must take CORS into consideration and set the Access-Control-Allow-Origin headers accordingly.
        microschemaControlsLocation: '/microschemaControls',
        microschemaControls: [
            // "geolocation/geolocationControl",
            // "example/exampleControl"
        ],

        // List any plugins to be loaded and made available to the Aloha editor.
        // (For available plugins see http://www.alohaeditor.org/guides/plugins.html)
        // If left empty, the following default plugins will be used:
        //  'common/autoparagraph',
        //  'common/contenthandler',
        //  'common/format',
        //  'common/highlighteditables',
        //  'common/list',
        //  'common/paste',
        //  'common/table',
        //  'common/ui'
        // plus a custom link plugin (mesh/mesh-link) for linking to other Mesh nodes.
        alohaPlugins: [],

        // Custom settings object for the Aloha editor. If left empty, the default configuration
        // will be used.
        alohaSettings: {}
    };


    window.meshUiConfig = meshUiConfig;

})(window, document);

Preview handling

The mesh ui will provide a preview button when editing nodes. A post request to a configureable url is being dispatchen when the button will be triggered. The post request will contain the node JSON data of the current editing state. This way a preview page can be easily rendered by custom frontend implementations.

JAVA REST client

You can add the following maven dependency and repository to your project to get the mesh rest client.

…
	<dependency>
		<artifactId>mesh-rest-client</artifactId>
		<groupId>com.gentics.mesh</groupId>
		<version>${mesh.version}</version>
	</dependency>
…
	<repositories>
		<repository>
			<id>maven.gentics.com</id>
			<name>Gentics Maven Repository</name>
			<url>https://maven.gentics.com/maven2</url>
			<releases>
				<enabled>true</enabled>
			</releases>
			<snapshots>
				<enabled>true</enabled>
			</snapshots>
		</repository>
	</repositories>
…

Usage:

	MeshRestClient client = MeshRestClient.create("localhost", 8080, vertx, BASIC_AUTH);
	client.setLogin("username", "password");
	client.login().toCompletable().await();

	client.findNodes("demo", new NodeRequestParameter().setExpandAll(true).setLanguages("en")).setHandler(rh -> {
		if (rh.succeeded()) {
			NodeListResponse list = rh.result();
			for(NodeResponse nodeResponse : list.getData()) {
				System.out.println(nodeResponse.getUuid());
				System.out.println(nodeResponse.getFields().getStringField("name").getString());
			}
		} else {
			rh.cause().printStackTrace();
		}
	});

License

  • Gentics Mesh is published under a commercial license. License Terms

  • GraphiQL is owned and developed by Facebook Inc.