Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions doc/src/main/hugo/content/docs/authentication.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -172,8 +172,6 @@ Gentics Mesh first and foremost keeps your content safe - all data including med
That is why Gentics Mesh instances ship with an included ```anonymous``` user/role/group set.
If no authentication details are provided Gentics Mesh will automatically try to authenticate with the user ```anonymous```.

TIP: Try our Gentics Mesh demo instance without authenticating yourself: ```https://demo.getmesh.io{apiLatest}/auth/me```. This link:/docs/api#auth[API endpoint] shows the currently authenticated user - which is ```anonymous```.

You can assign ```readPublished``` permissions to the ```anonymous``` role for all elements you want to be publicly available.

NOTE: Assigning further permissions would of course allow for other operations to be granted.
Expand Down
6 changes: 3 additions & 3 deletions doc/src/main/hugo/content/docs/cookbook/index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ This document aims to provide you with suggestions and hints on how to deal with

== Content

Handling contents is fairly easy. You can either identify and load content using the UUIDs or a regular web path.
Handling contents is fairly easy. You can either identify and load content using the UUIDs or a regular web path. Examples:

By Path: https://demo.getmesh.io{apiLatest}/demo/webroot/yachts/indian-empress
By Path: link:../api/#project__webroot__path__get[/api/v2/demo/webroot/yachts/indian-empress]

By Uuid: https://demo.getmesh.io{apiLatest}/demo/nodes/079ae5d5467447b99ae5d5467447b934
By Uuid: link:../api/#project__nodes__nodeUuid__get[/api/v2/demo/nodes/079ae5d5467447b99ae5d5467447b934]

You can either place the path or uuid to your content in a fragment `/demo#category/079ae5d5467447b99ae5d5467447b934` or in the regular web path `/demo/category/079ae5d5467447b99ae5d5467447b934`. Most modern single page application frameworks like angular or react support both variations.

Expand Down
117 changes: 27 additions & 90 deletions doc/src/main/hugo/content/docs/features.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,6 @@ For more details see the documentation on link:{{< relref "building-blocks.ascii

You can also specify dedicated paths for nodes using the ```urlFields``` schema property. You can add string or string list fields to your schema and list them via the ```urlFields``` property. Gentics Mesh will utilize these fields in nodes in order to retrieve the node.

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/webroot/cars/outatime

=== API endpoints

[options="header",cols="2*"]
Expand All @@ -67,10 +63,6 @@ https://demo.getmesh.io{apiLatest}/demo/webroot/cars/outatime

==== Response Sample

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/nodes/fc3c85be82584ae2bc85be82588ae2b0?resolveLinks=short

[source,json]
----
{
Expand Down Expand Up @@ -223,17 +215,7 @@ The demo app includes a navigation object showing just the top-level elements _A

=== Response Sample

Retrieving a navigation object using the projects root node ```/``` including the top level navigation menu items.

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/navroot/?resolveLinks=short&maxDepth=1

The same can be achieved using the node specific navigation endpoint. In this case you can specify the root node of your navigation by providing the node uuid.

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/nodes/688f7beae8d240bf8f7beae8d2a0bf2e/navigation?resolveLinks=short&maxDepth=1
Retrieving a navigation object using the projects root node ```/``` including the top level navigation menu items. The same can be achieved using the node specific navigation endpoint. In this case you can specify the root node of your navigation by providing the node uuid.

[source,json]
----
Expand Down Expand Up @@ -690,10 +672,6 @@ The ```breadcrumb``` property will be returned in all API responses containing n

=== Response Sample

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/nodes/fc3c85be82584ae2bc85be82588ae2b0?resolveLinks=short

[source,json]
----
{
Expand Down Expand Up @@ -846,7 +824,7 @@ For example, the following will not work:
| API endpoint
| Response code
| GET
| /api/v2/docs/hello-world/example-page.html
| {apiLatest}/docs/hello-world/example-page.html
| 404
|======

Expand All @@ -866,7 +844,7 @@ By prepending the path with a forward slash, the same request will resolve the n
| API endpoint
| Response code
| GET
| /api/v2/docs/hello-world/example-page.html
| {apiLatest}/docs/hello-world/example-page.html
| 200
|======

Expand Down Expand Up @@ -911,17 +889,11 @@ NOTE: Each segment of the URL must be URL-encoded. A node's contents must provid

==== Fetch node with UUID

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/nodes/fc3c85be82584ae2bc85be82588ae2b0?resolveLinks=short

Loading the node with the given UUID using API endpoint ```GET {apiLatest}/:projectName/nodes/:nodeUuid```.

==== Fetch node with WebRoot path

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/webroot/automobiles/ford-gt?resolveLinks=short
Loading the node with the given web path using API endpoint ```GET {apiLatest}/:projectName/webroot/path/to/the/node```.

=== Query binary content by path
The WebRoot API, furthermore, directly supports delivering binary content (e.g., images, documents, etc.) using the ```fileName``` meta-data field of the ```binary``` field.
Expand All @@ -932,39 +904,22 @@ NOTE: Downloads of resized images currently do not support byte range requests.

==== Fetch an image with UUID

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/nodes/df8beb3922c94ea28beb3922c94ea2f6/binary/image

Downloading a node's binary field with the given name using API endpoint ```GET {apiLatest}/:projectName/nodes/:nodeUuid/binary/:fieldName```.

==== Fetch an image with WebRoot path

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/webroot/images/ford-gt.jpg

TIP: When using a routing framework, in order to find out if a requested resource is binary data or JSON data you need to check the HTTP Content-Disposition response header. If it is set, it’s binary data.

=== Image manipulation by path
In case, the binary data is an image, the WebRoot API allows to directly perform
link:{{<relref "image-manipulation.asciidoc">}}[Image Manipulation] such as cropping and resizing.

==== Crop and resize an image with UUID

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/nodes/df8beb3922c94ea28beb3922c94ea2f6/binary/image?rect=10,100,800,400&w=300&crop=rect
==== Crop and resize an image

==== Crop and resize an image with WebRoot path

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/webroot/images/ford-gt.jpg?rect=10,100,800,400&w=300&crop=rect
The manipulation of an image, either over a UUID or path `GET` request, can be done by adding the corresponding query parameters, like: `?rect=10,100,800,400&w=300&crop=rect`

Find out more about this topic in our blog post about https://getmesh.io/blog/gentics-mesh-image-manipulation/[Gentics Mesh's Image Manipulation API and Interface].


== Link Resolving

Link resolving represents the counterpart of the <<webroot, WebRoot API>> - a node UUID can be resolved into a WebRoot path.
Expand Down Expand Up @@ -1382,17 +1337,10 @@ Most API responses within Gentics Mesh contain a list of permissions. This list

==== Example

.Try the example
[TIP]
Permission of user ```anonymous``` on node ```Delorean```
https://demo.getmesh.io{apiLatest}/demo/nodes/fc3c85be82584ae2bc85be82588ae2b0?version=published
// TODO provide new example node, remove read permission for this example node only, add ?version=published to example code
// TODO provide image with user - group - role for anonymous and permissions to specified node

The permissions has been requested as follows: link:/docs/api/#project__webroot__path__get[{apiLatest}/demo/nodes/fd58237c79d64bf198237c79d6bbf107?version=published]

[source,json,subs=attributes]
-----
// permissions for node https://demo.getmesh.io{apiLatest}/demo/nodes/fd58237c79d64bf198237c79d6bbf107?version=published
...
"permissions" : {
"create" : false, //create other nodes
Expand All @@ -1405,7 +1353,6 @@ https://demo.getmesh.io{apiLatest}/demo/nodes/fc3c85be82584ae2bc85be82588ae2b0?v
...
-----


The example above shows that the requesting user ```anonymous``` has the ```readPublish``` permission on the requested node, only. This means the user is allowed to read the published version of the node but not previous versions or a draft version of the requested element.

Furthermore the user is not allowed to
Expand Down Expand Up @@ -1453,16 +1400,10 @@ The link:/docs/api/#roles__roleUuid__permissions__pathToElement__get[```GET {api

For example, the link:{{< relref "references.asciidoc" >}}#_authentication[authenticated] ```admin``` user is able to find out the configured permissions for role ```Public User``` on node ```fc3c85be82584ae2bc85be82588ae2b0```.

.Try the example with user ```admin```
[TIP]
https://demo.getmesh.io{apiLatest}/roles/10447951fd264e6a847951fd266e6ae6/permissions/projects/217f8c981ada4642bf8c981adaa642c3/nodes/88fac3fbc61041c1bac3fbc610d1c182
Note, that a request with user ```anonymous``` will yield a _Missing object permissions_ error response.

link:/docs/api/#roles__roleUuid__permissions__pathToElement__get[```GET {apiLatest}/roles/10447951fd264e6a847951fd266e6ae6/permissions/projects/217f8c981ada4642bf8c981adaa642c3/nodes/88fac3fbc61041c1bac3fbc610d1c182```]

[source,bash,subs=attributes]
-----
GET https://demo.getmesh.io{apiLatest}/roles/10447951fd264e6a847951fd266e6ae6/permissions/projects/217f8c981ada4642bf8c981adaa642c3/nodes/88fac3fbc61041c1bac3fbc610d1c182

RESPONSE
{
"create": false,
Expand All @@ -1476,14 +1417,10 @@ RESPONSE

Alternatively, you can use query the element using the respective API endpoint (e.g. link:++/docs/api#project__nodes__get++[```GET {apiLatest}/projectName/nodes```]) and use the ```role``` query parameter to find out another role's (i.e. ```anonymous```) permissions on the element:

.Try the example with user ```admin```
[TIP]
https://demo.getmesh.io{apiLatest}/demo/nodes/88fac3fbc61041c1bac3fbc610d1c182?role=10447951fd264e6a847951fd266e6ae6
link:/docs/api#project__nodes__get[```GET {apiLatest}/demo/nodes/88fac3fbc61041c1bac3fbc610d1c182?role=10447951fd264e6a847951fd266e6ae6```]

[source,bash,subs=attributes]
-----
GET https://demo.getmesh.io{apiLatest}/roles/10447951fd264e6a847951fd266e6ae6/permissions/projects/217f8c981ada4642bf8c981adaa642c3/nodes/88fac3fbc61041c1bac3fbc610d1c182

RESPONSE
...
"permissions" : { // permissions of requesting user admin
Expand All @@ -1506,11 +1443,8 @@ RESPONSE
-----

==== Querying User Permissions
The endpoint link:/docs/api/#users__userUuid__permissions__path__get[```GET {apiLatest}/users/:userUuid/permissions/:path```] provides a shortcut for querying permissions for specific users directly, e.g., for user ```anonymous```, which is essentially inheriting all permissions from role ```anonymous```.

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/users/5fb9654c0b734e87b9654c0b736e8701/permissions/projects/217f8c981ada4642bf8c981adaa642c3/nodes/88fac3fbc61041c1bac3fbc610d1c182
The endpoint link:/docs/api/#users__userUuid__permissions__path__get[```GET {apiLatest}/users/:userUuid/permissions/:path```] provides a shortcut for querying permissions for specific users directly, e.g., for user ```anonymous```, which is essentially inheriting all permissions from role ```anonymous```.

=== Assigning & Revoking Permissions

Expand Down Expand Up @@ -1547,9 +1481,10 @@ The following example shows how to grant the ```Editor Role``` role the permissi

NOTE: Links used in the example require prior authentication with user admin (credentials: admin/admin). Please refer to the link:{{< relref "references.asciidoc" >}}#_authentication[authentication] section to learn about the different authentication mechanisms provided by Gentics Mesh. The https://insomnia.rest/[Insomnia] REST client can be used to build and invoke requests from your browser to Gentics Mesh.

link:/docs/api#roles__roleUuid__permissions__path__post[```POST {apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/users```]

[source,bash,subs=attributes]
-----
POST https://demo.getmesh.io{apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/users
{
"permissions": {
"create": false,
Expand All @@ -1570,9 +1505,7 @@ POST https://demo.getmesh.io{apiLatest}/roles/6754d83b086244d894d83b086204d87f/p
}
-----

You can query the updated permissions with user ```admin```:

https://demo.getmesh.io{apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/users
You can query the updated permissions with user ```admin```: link:/docs/api#roles__roleUuid__permissions__path__get[```GET {apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/users```]

===== Role permissions
All possible role permissions on users are summarized in the following table.
Expand Down Expand Up @@ -1604,9 +1537,10 @@ The following example shows how to grant the ```Editor Role``` role the permissi

NOTE: Links used in the example require prior authentication with user admin (credentials: admin/admin). Please refer to the link:{{< relref "references.asciidoc" >}}#_authentication[authentication] section to learn about the different authentication mechanisms provided by Gentics Mesh. The https://insomnia.rest/[Insomnia] REST client can be used to build and invoke requests from your browser to Gentics Mesh.

link:/docs/api#roles__roleUuid__permissions__path__post[```POST {apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/groups/df81c23d9ff1450081c23d9ff195005e```]

[source,bash,subs=attributes]
-----
POST https://demo.getmesh.io{apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/groups/df81c23d9ff1450081c23d9ff195005e
{
"permissions": {
"create": false,
Expand All @@ -1630,12 +1564,13 @@ POST https://demo.getmesh.io{apiLatest}/roles/6754d83b086244d894d83b086204d87f/p

You can query the updated permissions with user ```admin```:

* https://demo.getmesh.io{apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/groups/df81c23d9ff1450081c23d9ff195005e
* https://demo.getmesh.io{apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/users
* link:/docs/api#roles__roleUuid__permissions__path__get[```GET {apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/groups/df81c23d9ff1450081c23d9ff195005e```]
* link:/docs/api#roles__roleUuid__permissions__path__post[```GET {apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/users```]

* or alternatively with
https://demo.getmesh.io{apiLatest}/groups/df81c23d9ff1450081c23d9ff195005e?role=6754d83b086244d894d83b086204d87f
https://demo.getmesh.io{apiLatest}/groups/df81c23d9ff1450081c23d9ff195005e/users?role=6754d83b086244d894d83b086204d87f
or alternatively with

* link:/docs/api/#groups__groupUuid__get[```GET {apiLatest}/groups/df81c23d9ff1450081c23d9ff195005e?role=6754d83b086244d894d83b086204d87f```]
* link:/docs/api/#groups__groupUuid__users_get[```GET {apiLatest}/groups/df81c23d9ff1450081c23d9ff195005e/users?role=6754d83b086244d894d83b086204d87f```]

===== Role permissions
All possible role permissions on groups are summarized in the following table.
Expand Down Expand Up @@ -1669,9 +1604,10 @@ The following example shows how to grant the ```Editor Role``` role permissions

NOTE: Links used in the example require prior authentication with user admin (credentials: admin/admin). Please refer to the link:{{< relref "references.asciidoc" >}}#_authentication[authentication] section to learn about the different authentication mechanisms provided by Gentics Mesh. The https://insomnia.rest/[Insomnia] REST client can be used to build and invoke requests from your browser to Gentics Mesh.

link:/docs/api/#roles__roleUuid__permissions__path__post[```POST {apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/roles```]

[source,bash,subs=attributes]
-----
POST https://demo.getmesh.io{apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/roles
{
"permissions": {
"create": true,
Expand All @@ -1694,10 +1630,11 @@ POST https://demo.getmesh.io{apiLatest}/roles/6754d83b086244d894d83b086204d87f/p

You can query the updated permissions with user ```admin```:

* https://demo.getmesh.io{apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/roles
* link:/docs/api/#roles__roleUuid__permissions__path__get[```GET {apiLatest}/roles/6754d83b086244d894d83b086204d87f/permissions/roles```]

or alternatively with

* or alternatively with
https://demo.getmesh.io{apiLatest}/roles?role=6754d83b086244d894d83b086204d87f
* /docs/api/#roles__get[```GET {apiLatest}/roles?role=6754d83b086244d894d83b086204d87f```]

===== Role permissions
All possible role permissions on roles are summarized in the following table.
Expand Down
15 changes: 0 additions & 15 deletions doc/src/main/hugo/content/docs/getting-started.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -12,21 +12,6 @@ Gentics Mesh is a headless CMS which provides developers with HTTP based API's t

A headless CMS just provides an API (REST/GraphQL) instead of serving or rendering the pages directly. The template handling is done in your front-end. This gives the developers the freedom to choose the technology stack they like. The CMS no longer dictates this.

== Quickstart

If you don't have much time:

* Try the link:https://demo.getmesh.io/mesh-ui/[UI] with login (admin/admin) for playing around with Gentics Mesh and it's user interface.
* Changes can be viewed in the link:https://demo.getmesh.io/demo/[demo front-end]

[subs=attributes]
++++
<ul><li>
<a href="https://demo.getmesh.io/api/v1/demo/graphql/browser/#query=%7B%0A%20%20node(path%3A%20%22%2Fyachts%2Fpelorus%22)%20%7B%0A%20%20%20%20fields%20%7B%0A%20%20%20%20%20%20...%20on%20vehicle%20%7B%0A%20%20%20%20%20%20%20%20name%0A%20%20%20%20%20%20%20%20description%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D" target="_blank">You can also use GraphQL</a></li></ul>
++++

* Head over to the <<tldr,TL;DR>> section to find out everything you need to know and what makes Gentics Mesh special.

== Run with Docker
=== Run empty demo container

Expand Down
11 changes: 1 addition & 10 deletions doc/src/main/hugo/content/docs/graphql.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -53,11 +53,6 @@ The search query is an escaped JSON object which represents the a regular https:

include::content/docs/examples/graphql/node-search-query[]

[subs=attributes]
++++
<a href="https://demo.getmesh.io{apiLatest}/demo/graphql/browser/#query=query%20stuff(%24esQuery%3A%20String)%20%7B%0A%20%20nodes(query%3A%20%24esQuery)%20%7B%0A%20%20%20%20elements%20%7B%0A%20%20%20%20%20%20uuid%0A%20%20%20%20%20%20...%20on%20vehicle%20%7B%0A%20%20%20%20%20%20%20%20fields%20%7B%0A%20%20%20%20%20%20%20%20%20%20slug%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%20%20totalCount%0A%20%20%7D%0A%7D%0A&variables=%7B%0A%20%20%22esQuery%22%3A%20%22%7B%5C%22query%5C%22%3A%7B%5C%22query_string%5C%22%3A%7B%5C%22query%5C%22%3A%5C%22car%5C%22%7D%7D%7D%22%0A%7D&operationName=stuff" target="_blank">Example using variables</a>
++++

=== Using pagination

Similar to the REST API a value based pagination system is implemented.
Expand Down Expand Up @@ -147,11 +142,7 @@ Many tasks can be done by both the search and the filtering feature. Here are a

We have integrated the interactive https://github.com/graphql/graphiql[GraphiQL]footnote:[https://github.com/graphql/graphiql[GraphiQL] is owned and developed by Facebook Inc. Usage is subject to the https://github.com/gentics/mesh/blob/dev/verticles/graphql/src/main/resources/graphiql/LICENSE[LICENSE AGREEMENT For GraphiQL software].] browser into Gentics Mesh so you can easily play with the API.

.Try the example
[TIP]
https://demo.getmesh.io{apiLatest}/demo/graphql/browser/[Live Demo]

Alternatively, you can download Gentics Mesh and test the API locally.
You can link:../getting-started/#_run_with_docker[download Gentics Mesh] and test the API locally.
Once authenticated you can access the interactive GraphiQL browser at ```{apiLatest}/:projectName/graphql/browser/``` .

NOTE: The GraphiQL browser currently does not support the `branch` or `version` query parameter.
Expand Down
Loading