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.
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:
- A resource access grant must be configured for public users to allow the POST method to the grant with signature
_registration
- jsonrestservlet.user.autocreate must be enabled in structr.conf to enable automatically creating users
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 asnode.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.