References

REST API

The Gentics Mesh REST API provides endpoints enabling you to invoke CRUD operations on just ANY Gentics Mesh element. There are many things you can do with the REST API. To name a few:

  • Obviously you can create, update & fetch multilingual content items as well as tag them.

  • But you can also define the schemas, i.e. the content types of your project.

  • You can do file upload and image manipulation.

  • WebRoot Paths for fetching content by path as well as automatic link resolving greatly simplify the integration with any routing framework.

  • Fetching dynamic navigation menus and breadcrumbs based on the content structure will make your editors happy.

  • With Elasticsearch under the hood you can search your content.

  • You can manage your users and their permissions on content elements.

All REST API responses are available in JSON, only, except for binary data.

Query Parameters

The REST API end points can be used in combination with a set of query parameters, all of which are documented for the specific end points in the Gentics Mesh REST API reference. Following, we provide an overview of the most common query parameters.

Paging Parameters

Name Type Mandatory Description

order

string (default: UNSORTED)

false

Field order (ASC/DESC/UNSORTED) to sort the result by.

page

number (default: 1)

false

Number of page to be loaded.

perPage

number

false

Number of elements per page.

sortBy

string

false

Field name to sort the result by.
Paging is not applied by default. It is advised to include the perPage query parameter whenever possible to reduce the response size.

Versioning Parameters

Name Type Mandatory Description

branch

string

false

Specifies the branch to be used for loading data. The latest project branch will be used if this parameter is omitted.

version

string (default: draft)

false

Specifies the version to be loaded. Can either be published/draft or version number. e.g.: 0.1, 1.0, draft, published.
Node Parameters
Name Type Mandatory Description

lang

string

false

ISO 639-1 language tag of the language which should be loaded. Fallback handling can be applied by specifying multiple languages in a comma-separated list. The first matching language will be returned. If omitted or the requested language is not available then the defaultLanguage as configured in mesh.yml will be returned.

resolveLinks

string

false

The resolve links parameter can be set to either short, medium or full. Stored mesh links will automatically be resolved and replaced by the resolved webroot link. With the parameter set the path property as well as the languagesPath property (for available language variants) will be included in the response. Gentics Mesh links in any HTML-typed field will automatically be resolved and replaced by the resolved WebRoot path. No resolving occurs if no link has been specified.
Role Permission Parameters
Name Type Mandatory Description

role

string

false

The role query parameter take a UUID of a role and may be used to add permission information to the response via the rolePerm property which lists the permissions for the specified role on the element. This may be useful when you are logged in as admin but you want to retrieve the editor role permissions on a given node. Endpoint: /api/v2/:projectName/nodes?role=:roleUuid

Examples

We have set up a Gentics Mesh instance for demo purposes, that you can play with.

Let’s see what’s inside…​

List all projects. Well, it’s just our demo project.
https://demo.getmesh.io/api/v2/projects
Want to fetch all content items including media? With pretty URLs? Here you go
https://demo.getmesh.io/api/v2/demo/nodes/?resolveLinks=short
OK, let’s load a single content item.
https://demo.getmesh.io/api/v2/demo/nodes/fc3c85be82584ae2bc85be82588ae2b0
And now forget about UUIDs and do it with its corresponding WebRoot path
https://demo.getmesh.io/api/v2/demo/webroot/automobiles/ford-gt

That’s easy. Well, what about images?

That’s the image node
https://demo.getmesh.io/api/v2/demo/nodes/df8beb3922c94ea28beb3922c94ea2f6
And that’s the actual image
https://demo.getmesh.io/api/v2/demo/nodes/df8beb3922c94ea28beb3922c94ea2f6/binary/image
Let’s do some resizing
https://demo.getmesh.io/api/v2/demo/nodes/df8beb3922c94ea28beb3922c94ea2f6/binary/image?width=400
And now again with a readable WebRoot path
https://demo.getmesh.io/api/v2/demo/webroot/images/ford-gt.jpg?width=400
The Insomnia REST client can be used to build and invoke requests from your browser to Gentics Mesh.

HTTP

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.

CORS

The Cross-Origin Resource Sharing mechanism enables Gentics Mesh to configure cross-domain access controls.

You can read up on this topic on the MDN article.

The CORS header handling can be configured using the httpServerOptions.corsAllowedOriginPattern, httpServerOptions.corsAllowCredentials and httpServerOptions.enableCors configuration settings.

Multi Site Example

The corsAllowedOriginPattern setting accepts a regular expression pattern. It is thus possible to allow multiple origins.

Example:

httpServer:
  corsAllowedOriginPattern: "http://mydomain:5000|http://mydomain2:5000"
  corsAllowCredentials: true
  enableCors: true

ETag Handling

Most endpoints of the Gentics Mesh REST API will return an ETag header within the response.

ETag:W/"1125-7cc5c6fb"

These headers values can be used to implement or utilize existing web caching solutions.

An ETag validation occurs once the ETag is passed along a http request.

If-None-Match:W/"1125-7cc5c6fb"

Gentics Mesh will compare the provided ETag with the current state of the content and return a 304 response if the ETag is the same and the response did not change. Updating the requested resource will alter its ETag and thus another request would return the response which includes the current ETag.

ETag Handling can be disabled for each request via the ?etag=false query parameter. This will increase performance when ETag headers are not needed.

HTTPs

Server side SSL support can be enabled via the server.ssl flag or the MESH_HTTP_SSL_ENABLE environment variable. SSL support is disabled by default.

In most cases a reverse proxy like Traefik which handles HTTPs is a more viable solution compared to handle HTTPs by Gentics Mesh Server.

Ports

The HTTPs server port can be configured via server.sslPort or environment variable MESH_HTTPS_PORT. The default is port 8443.

The HTTP server port uses the server.port setting with default 8080.

You can also turn off the HTTP server via the server.http setting.

Certificates

A server certificate and server key in PEM format has to be provided. The server.certPath and server.keyPath settings can be used to set the path to the generated files.

For testing purposes you may want to create a self signed certificate like this:

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

Client Certificate

Gentics Mesh also support client certificate handling. The server can be configured to reject, request or require client certificates.

Client certificates are a good option to ensure that the SSL connection between client and server is trusted by both parties.

Please note that client certificates will currently not provide a way to handle authentication. The send request still needs to provide an API Key to be authenticated and mapped to a user.
All certs / keys must be in PEM format.

Client Authentication Modes

The server.clientAuthMode (Env: MESH_HTTP_SSL_CLIENT_AUTH_MODE) setting can be used to control the client authenticaton mode.

The Gentics Mesh HTTPs server supports three client authentication modes:

  • none - Reject client certificates during SSL handshake (default)

  • request - Request client certificate. A client certificate will be used when provided. The request will also work when omitting the client cert.

  • require - Requiring a client certificate. The ssl handshake will fail when no client certificate was provided.

The server.trustedCertPaths (Env: MESH_HTTP_SSL_TRUSTED_CERTS) setting can be used to set a list of certificates which will be trusted by the server.

API Tools

Gentics Mesh provides the /raml endpoint to easily extract the API documentation into third party tools.

Insomnia

The insomnia REST and GraphQL client can be used to quickly and efficiently interact with the API.

You can download and import mesh-insomnia-v1.json in your Insomnia REST workspace to get a pre-defined set of useful requests and examples.

Postman

Here is a quick guide to import the API into Postman:

  • Once the Postman app is started go to "Import" > "Import from Link"

  • Input the URL to the /raml endpoint of your Mesh instance.

  • You can also try https://demo.getmesh.io/api/v2/raml to get it form our demo

Make use of the params and workspace parameters to maximize your productiviy. Check out the Postman documentation about URL setup for more.

Keep in touch

Find us on Twitter @genticsmesh

Get help on stackoverflow

Ask us anything on Gitter

Dive into the code at GitHub

Legal

Licensed under Apache License v2.0 | Imprint

Made in Vienna - the most livable city in the world

Cookie Preferences

Choose if this website is only allowed to use functional cookies and/or marketing cookies.

Cookie Preferences

Choose if this website is only allowed to use functional cookies and/or marketing cookies.