You have been redirected from an outdated version of the article. Below is the content available on this topic. To view the old article click here.

REST

Search results for "REST"

List of REST Endpoints

URL Description Supported methods
/structr/rest/_env Structr runtime environment information GET
/structr/rest/_schema Schema information endpoint GET
/structr/rest/_schemaJson Schema JSON output endpoint GET, POST
/structr/rest/cypher Direct Cypher query endpoint GET, POST
/structr/rest/globalSchemaMethods/... Root path for global schema method execution POST
/structr/rest/login Login endpoint POST
/structr/rest/logout Logout endpoint POST
/structr/rest/token JWT endpoint POST
/structr/rest/maintenance Root path for maintenance command execution POST
/structr/rest/registration Endpoint for the User Self-Registration process POST
/structr/rest/reset-password Endpoint for the Reset Password process POST

Signature

Type URL Signature
Collection /structr/rest/Project Project
Collection with view /structr/rest/Project/ui Project/_Ui
Collection with view /structr/rest/Project/info Project/_Info
Entity with UUID /structr/rest/Project/362cc05768044c7db886f0bec0061a0a Project
Entity with UUID and view /structr/rest/Project/362cc05768044c7db886f0bec0061a0a/info Project/_Info
Subcollection /structr/rest/Project/362cc05768044c7db886f0bec0061a0a/tasks Project/Task
Schema Method /structr/rest/Project/362cc05768044c7db886f0bec0061a0a/doUpdate Project/DoUpdate

REST

Mode set to 'REST'. Type 'help' to get a list of commands.
anonymous@Structr> help
as - Runs a REST command in the security context of a given user.
auth - Sets authentication information for subsequent requests.
del - Executes a REST DELETE request.
delete - Executes a REST DELETE request.
get - Executes a REST GET request and returns the JSON or parts of it.
help - Prints a list of all commands and a short help text. Use 'help <command> to get more details.
post - Executes a REST POST request.
put - Executes a REST PUT request.
anonymous@Structr>

REST Query

The REST repeater configuration allows entering a REST URI and supports all query features a regular REST query supports. This includes sort, order, page, pageSize, range queries etc.

It is not necessary to include the REST base path /structr/rest/.
Further, it is not necessary to create resource access grants for these REST queries as they are run internally.

JsonRestServlet

jsonrestservlet.defaultview Default view to use when no view is given in the URL.
jsonrestservlet.outputdepth Maximum nesting depth of JSON output.
jsonrestservlet.user.class User class that is instantiated when new users are created via the servlet.
jsonrestservlet.user.autologin Only works in conjunction with the jsonrestservlet.user.autocreate key. Will log in user after self registration.
jsonrestservlet.user.autocreate Enable this to support user self registration.

Create Nodes

To create data in Structr, you can use the HTTP POST verb with a JSON document in the request body. The target URL for the POST request is determined by the type of object you want to create. Structr automatically creates corresponding REST Endpoints for all types in the data model and makes them available under /structr/rest/<Type>. In the following example, we create a new Project node, so the REST URL is /structr/rest/Project, which addresses the Collection Resource for that type.

Import JSON

Since Javascript Object Notation (JSON) is the default format for all data going over the REST interface, you can import JSON data very easily using REST. You can find more information about that in the REST Guide and in the REST API section of the Fundamental Concepts document.

Registration Resource

The self-registration should be done via the registration resource. It is available under /structr/rest/registration.

An un-authenticated user can issue a HTTP POST to that resource to begin the registration process. The accepted input attributes are configured in the configuration registration.customuserattributes. eMail is always supported and often used as a single attribute for registration.

The registration is then started by the user by making a HTTP POST request (via a signup form) to /structr/rest/registration with the following body:

fetch("http://localhost:8082/structr/rest/registration", {
  method: "POST",
  body: JSON.stringify({
    eMail: "user.name@mail.com"
  })
})

The self-registration process would then send a mail using the above templates.

Notes:

Password Reset Resource

The reset password process should be done via the reset password resource. It is available under /structr/rest/reset-password.

An un-authenticated user can issue a HTTP POST to that resource to begin the registration process. The accepted input attributes are configured in the configuration registration.customuserattributes. eMail is always supported and often used as a single attribute for registration.

The reset password process is then started by the user by making a HTTP POST request to /structr/rest/reset-password with the following body:

fetch("http://localhost:8082/structr/rest/reset-password", {
  method: "POST",
  body: JSON.stringify({
    eMail: "user.name@mail.com"
  })
})

The reset password process would then send a mail using the above templates.

Notes:

  • A resource access grant must be configured for public users to allow the POST method to the grant with signature _resetPassword
  • the configuration setting JsonRestServlet.user.autologin must be set to true to enable auto-login with the link in the email
  • the link in the mail is only valid once

Resource Access Grants

This part of Structr’s backend UI is the place where the entry points of Structr’s HTTP REST Service can be configured.

While the security system of Structr is focused on users and their security context (i.e. does the user has access to a given database entity?), the checking of resource access grants is focused on the URL path (the resource) of an HTTP request.

More precisely, if a user requests all entities of a given schema type via Structr’s REST interface with a call to the URL /structr/rest/SchemaType, Structr will check if the user is logged into the system and if a GET request on the resource /SchemaType is permitted for authenticated users. If the user is not logged into the system the GET permission for non-authenticated users has to be set for that resource.

Only when the permission for the resource is set, Structr will then check if user has grants for the actual database content and the entities of the type SchemaType.

Relationship Details Dialog

The Cascading Delete settings allow configuration of what happens when either end of the relationship is deleted. The possible values are explained in-depth in the help popup in the dialog.
Automatic Creation of Related Nodes configures if it is allowed to include nested nodes in a REST POST request for this relationship. A node with the given property set is automatically created and linked to the node. If the nested node contains an id attribute (or another property marked as unique) a node is searched for that property and linked if found.

Permission Resolution allows configuration of rights propagation in the graph. If NONE is selected, no rights propagation is applied for this relationship. If SOURCE_TO_TARGET is selected the rights are propagated along the relationship direction to the next node. For TARGET_TO_SOURCE the rights propagation is works against the relationship direction. For ALWAYS the direction of the relationship does not matter and rights propagation is always applied.
Specific rights (Read, Write, Delete, AccessControl) can be added, kept or removed according to the propagation configuration. If a user has read rights to the previous node and Read is configured to Keep, the user also has read rights for the next node. (Specific User/Group rights are applied before using permission propagation - i.e. if a user has specific rights configured for a node, permission resolution is not evaluated as user rights are more specific).
Along the way of permission propagation, properties can be hidden in order to hide sensitive information from users who get rights from permission propagation. The property names can be separated by comma , or space character.

There are 3 tabs where the functionality of the type can be configured:

  • Local Attributes
    A Custom Type can be extended with dynamic properties to provide the data model for the intended use-case. This list contains all local properties (meaning they are defined on this type directly).
  • Views
    The properties of a type can be combined into named Views, which are accessible under an individual REST URL. Access to these URLs can be configured independently for each HTTP method using Resource Access Grants, which makes them an ideal tool to create specialised endpoints for different client applications (e.g. mobile clients etc.).
  • Methods
    There are different kinds of methods - callback methods and entity methods. Callback methods are automatically executed by the framework upon certain lifecycle events and have a strict naming convention. Entity methods are called by the user/programmer.
    Entity methods are not automatically run by the framework and must be called manually. This either means making a POST request to /structr/rest/(Type)/(<a data-id="7c9c8218bced42bab66868373e64d885" class="mention">UUID</a>)/(methodName) or in serverside JavaScript as node.methodName();

REST

The REST mode provides a very simple REST client that runs as if you were to access Structr externally. This means that your requests are made without authentication, as long as you don’t authenticate them. You can use the REST client to simulate access from the outside and test Resource Access Grants etc.

Commands

The following commands can be used in REST mode. Please refer to the REST Guide for more information about the REST interface and its features.

REST Endpoints

All REST Endpoints in Structr share the same base path, /structr/rest relative to the base URL of your Structr installation. There are two types of REST endpoints in Structr.

Depending on the type of resource, different request methods (GET, PUT, POST, PATCH, DELETE) are allowed.

Learn More

If you want to learn more about the REST API, please read the REST Guide or the section about the REST API in the Fundamental Concepts document.

Overview

Structr automatically creates REST endpoints for all types in the data model. There are different types of endpoints: collection resources, which provide access to collections of objects of the corresponding type, and entity resources that allow you to read, update or delete individual objects. To learn more about the basics of REST APIs in Structr, please read the chapter about the Structr REST API in the Fundamental Concepts document.