In a previous blog post, we showed you how to get started with the 4D REST server. We walked you through different CRUD operations using Postman and pointed you to the full REST documentation. In this blog post, We’ll explain how sessions work in 4D. This understanding will ensure that you’ll be able to build a session-based authentication system using the 4D REST server.
4D rest sessions
If you’re interested in building an authentication system, a session-based system is what you’re looking for!
Connections to the 4D REST server are session-based. This means that the 4D server creates a session when the first request is sent by the client and sends back a session cookie to it (WASID4D). For all subsequent requests, the client must return this session cookie in the header of the request. This is contrary to token-based authentication where no session is persisted on the server-side, but is stored on the client.
Configure the REST server
Now that we’ve got a good understanding of how sessions are handled, let’s move forward. Before we can get started, you need to start and configure the 4D REST server. Please refer to this blog post or the documentation center before going any further.
On REST authentication method
The On REST Authentication database method provides you with a custom way of controlling how REST sessions are opened on 4D. When a request to open a REST session is received, the connection identifiers (e.g. user name and password) are provided in the header of the request. The On REST Authentication database method is called so that you can evaluate these identifiers, and return True (session opening accepted) or False (session opening rejected).
Note: While this database method is used to code your own access control to the database, access can be also restricted using a 4D user group. When you expose the database, select the group allowed access on the Database Settings > Web > REST resource tab. Check out this blog post for a memory refresher.
Open a session
To illustrate a session opening, we’re imagining a submission form with a login and password. We’ll be using Postman to send the credentials in the headers of the POST request. In order to open a session in your 4D application through REST, use $directory/login:
Let’s go back to 4D and see what’s going on.
As you can see, the database method receives four parameters:
- $1 for the user name,
- $2 for the password,
- $3 returns True if the password is hashed and False if it’s not,
- $4 holds the IP address of the caller.
Note: In the real world, passwords should be hashed and not sent in the clear. For sending a hashed password you can use the hashed-password-4D parameter instead of password-4D. Check out this code example that shows how to proceed.
Once the request is received, the server opens a session and sends back a session cookie to the client (WASID4D):
Now that our session has been created, how can we pass its ID back in consequent HTTP requests?
Wait … why do we have to do this in the first place?
Session management
HTTP is a “stateless” protocol … each time a client connects to a web page, it opens a separate connection to the web server. The server doesn’t keep a record of any previous client requests. Imagine thousands of clients connect to the server, how would it know which session is yours? That’s where the session ID comes into play. Through this exchange of session IDs, the state is maintained. What exactly does that mean? Well it means that in order to reuse the same session, you need to ensure that all subsequent REST requests include the session ID in the request’s “Cookie” header. Otherwise, a new session will be opened (and a new session means a new license).
Example
The way to handle sessions actually depends on your HTTP client. Let’s say we’re in a context where requests are handled through the HTTP Request command.
To include the session ID in the header, we first need to find it. Easy! We know that the session has a WASID4D key, so we just need to look for this key in the headers’ values with the Find in array command :
Find in array($headerValues;"WASID4D@")
Once found, let’s extract it:
$start:=Position("WASID4D";$cookie) The $uuid will host the session ID that will be sent in all subsequent requests. Find the complete example here.
$end:=Position(";";$cookie)
$uuid:= Substring($cookie;$start;$end-$start)
Control the session timeout
By default, the session inactivity timeout is 60 min and can’t be less. However, you can increase the timeout length with the value of the “session-4D-length” parameter that can be passed in POST headers with the $directory/login method.
One more thing
4D Server has a session storing entity selections based on previous queries or order commands. That’s why when the next “range” (or chunk) of data is needed, it doesn’t need to query/order again, it simply needs to send the next set of data. This mechanism allows the usage of transactions, pessimistic locking, and more.
What’s next?
The REST server has been greatly enhanced with 4D v18, and more features are coming in the future. In the meantime, we’ll keep providing you with examples and practical use cases. Feel free to join the discussion on the 4D forum.