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

page

number (default: 1)

false

Number of page to be loaded.

perPage

number

false

Number of elements per page.

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 link:{{< relref "features.asciidoc" >}}#_link_resolving[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/v1/: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/v1/projects
Want to fetch all content items including media? With pretty URLs? Here you go
https://demo.getmesh.io/api/v1/demo/nodes/?resolveLinks=short
And now forget about UUIDs and do it with its corresponding WebRoot path
https://demo.getmesh.io/api/v1/demo/webroot/automobiles/ford-gt

That’s easy. Well, what about images?

The Insomnia REST client can be used to build and invoke requests from your browser to Gentics Mesh.

HTTP details

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.

Using the API RAML Documentation in other Tools

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

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/v1/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.