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.

request

The request keyword returns a reference to the current HTTP request object (see javax.servlet.http.HttpServletRequest). It can be used to access HTTP GET request parameters.

Example

The request object of a page that was accessed with the URL

http://127.0.0.1:8082/structr/rest/my-page?name=test&value=123

looks like this:

request.name = "Test"
request.value = 123

Note

To access parameters from HTTP POST requests, please use the retrieve() function.

Warning

If you are running methods from a Cron job, the request object is null, so if you are using that method in another context where you want to supply request parameters, in order for it to stay error-free in the Cron context, you need to null-check the request.

let request = Structr.get('request');
if (Structr.empty(request)) {
    // empty request so we are probably in a Cron context
}

Search results for "request"

request

The request keyword returns a reference to the current HTTP request object (see javax.servlet.http.HttpServletRequest). It can be used to access HTTP GET request parameters.

requestStore

Can be used to store data in-memory for the duration of the current request. The requestStore can be accessed like a simple JavaScript object and can store arbitrary things.

This keywords uses the same data store as the $.store() and $.retrieve() functions but is easier to use in JavaScript. The newer set of helper functions for this keyword is preferred versus store() and retrieve().

get_request_header()

Returns the value of the HTTP request header with the given name. This method can be used both in Entity Callback Functions and in the Page Rendering process to obtain the value of a given HTTP header, allowing the user to use HTTP headers from their web application clients to control features of the application.

get_request_header(name)

request_store_get()

Retrieves a stored value from the request level store.

request_store_get(key)

request_store_delete()

Removes a stored value from the request level store.

request_store_delete(key)

request_store_has()

Checks if a key is present in the request level store.

request_store_has(key)

request_store_get_keys()

Lists all keys stored in the request level store.

request_store_get_keys()

request_store_put()

Stores a value in the request level store.

request_store_put(key, value)

Logging

nodeextender.log Enables the logging of generated Java code of the dynamic schema entities to the logfile. This setting allows you to investigate and debug the generation of Java code for your schema entities in cases where something goes wrong.
nodeextender.log.errors Enables the logging of Java compilation errors when compiling the dynamic schema of your application.
log.requests Enables full request logging for all requests handled by Structr. Caution, the log file can get very large when a lot of requests with lots of content are made.
log.debug Controls the debug() built-in function, which will behave exactly like the log() function if enabled.
log.functions.stacktrace Enables stacktrace logging for script calls and built-in functions. If enabled, a scripting error will write the full Java stack trace to the logfile.
log.prefix Sets the prefix for the request log file that is written when log.requests is enabled.
log.javascript.exception.request Adds path, queryString and parameterMap to JavaScript exceptions (if available) if enabled.
log.directorywatchservice.scanquietly Prevents logging of each scan process for every folder processed by the directory watch service.

HTTP

The Hypertext Transfer Protocol (HTTP) is a stateless communication protocol that is based on the exchange of plain text messages (request and response). A request message consists of a request line that contains the HTTP method, the URL of the requested resource (request URL) and HTTP version, a list of key-value pairs (request headers), and an optional request body. A response message consists of a response line with the HTTP status code, a list of response headers, and an optional response body.

HTTP Methods

A PUT request tells the server to replace the contents of the location in the request URL with the contents from the request body. In Structr, a PUT request will only work with a Collection Resource. The implementation of the PUT method in Structr differs from the original specification in that the request body does not replace the original contents, but only changes the values of the properties included in the request. That means that the PUT method in Structr is closer to the specification of PATCH than of PUT.

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>

HTTP Methods

A GET request tells the server to return the content of a particular resource. The location of the requested resource is specified in the request URL, along with HTTP headers that set the desired language, content type, encoding and other metadata. GET requests usually don’t contain a request body, although it is not forbidden by the specification.

A POST request tells the server to invoke the function that is associated with the location in the request URL. In Structr, a POST request can invoke two different functions, based on the target resource in the URL.

  • If the target resource is a Collection Resource, a POST request will create a new object in that collection.
  • If the target resource is an Entity Resource that points to a schema method, the method is executed. Any parameters present in the request body will be passed to the method.
  • All other resources will return HTTP status 405 Method Not Allowed.

Authentication - Login

A user can log into the application with an HTTP POST request to the REST interface of Structr. In response Structr will return a cookie with key JSESSIONID and a new session id as value. A browser will send this session id automatically in subsequent requests to Structr where it can be used to run the request in the context of the logged in user.

The URL for the request

REST Errors

HTTP status code HTTP Status Text Description
400 Bad Request Client error, the request is not valid and should not be repeated
401 Unauthorized Client error, the request needs a user
403 Forbidden Client error, the request needs a user
404 Not Found Client error, access to non-existing resource (can be simply invisible)
405 Bad Method Client error, access to an endpoint using the wrong HTTP verb
422 Unprocessable Entity Client error, data format error, structural error, schema constraint violation etc.

Request Parameters

The request URL can contain a so-called query component, which starts at the first ? character in the URL and consists of a list of key-value pairs separated by &. These key-value pairs are called request parameters. The following example shows a request URL with two request parameters, name and message.

Graph-based permission resolution

In the above example, the schema is configured in such a way that users with the maintains relationship to a ProductGroup will have access to any Product object in the group they maintain, but not to the subgroups of the given group.

Schema relationships that are configured to allow domain permission resolution are called active relationships. Active relationships are displayed in a different color than normal relationships in the schema editor.

When a non-admin user accesses a private object (e.g. a Product node from the above example schema), Structr tries to find a path which ADDs the requested right or KEEPs the requested right from a node the user has the specific right on.

In detail: We assume that a user who has a read permission grant to a ProductGroup tries to access a Product contained in that group (for which the user does not have direct rights).
Structr will then traverse the active relationship(s) until a path is found which ADDs or KEEPs the requested right.

Successful path evaluation:

  • The (ProductGroup)-[:contains]->(Product) relationship is configured to keep read and write
  • The effective permissions at the end of the evaluation process are read and write

Unsuccessful path evaluation:

  • If a user who has a read permission grant to a product that is not contained in the product group he has access to, but in a subgroup of the given group, Structr will not be able to find a connected path of active relationships and will fail the permission resolution.
  • The user does not have any permission grants set on any node or only visibility flags are set on the data nodes.

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.

Users and Groups

Users can log into the application and are given a cookie which Structr can resolve in subsequent requests to the actual user entity in the system. This means that every request to Structr is evaluated in the context of the user who is making the request.