May 25 is TMS XData training day, the day after TMS RADical Web Day


Monday, May 07, 2018

Our TMS XData expert Wagner R. Landgraf travels from Brasil to Germany especially for the TMS RADical Web training day on May 24th at Marienfeld, Germany. TMS XData is the tool for Delphi developers to enable creating fast, easy and secure REST APIs to access cloud databases from desktop, mobile and web client applications. As there is a demand for in-depth training on this powerful TMS XData product, we decided to also offer a possibility for training on TMS XData on May 25th, the day after the TMS RADical Web training day and available for an ultra limited number of developers to ensure a personal, hands-on and very interactive training.

TMS XData Training Day (all sessions in English)

09h00 - 09h30
Welcome, coffee, meeting

09h30 - 10h30
1. Introduction to TMS Sparkle and TMS XData
a) Presenting TMS Sparkle concepts: http.sys, modules, example server
b) Creating a XData module with a “hello world” operation
c) XData overal concepts: service operations and entities

10h30 - 11h00
Coffee break / Instructor available for questions and discussion

11h00 - 12h00
2. Service Operations
a) Creating service operations - interface and implementation
b) Parameter passing: in body, in url
c) Supported parameter types: scalar, structured and PODO
d) Parameter by reference
e) Memory Management
f) Using/receiving TStream

12h00 - 13h30
3-course warm lunch / instructor available for questions and discussion
13h30 - 15h00
3. Database access
a) “Traditional” approach
b) Connection Pool
c) Aurelius integration in service operations
d) Entity publishing: CRUD operations
e) Querying, paging and counting entities
f) Entity set permissions

15h00 - 15h30
Coffee break / Instructor available for questions and discussion

15h30 - 16h15
4. Desktop client-side development
a) TXDataClient overview
b) Invoking service operations
c) CRUD operations from client
d) Memory management

16h15 - 17h00
5. Web client-side development
a) TXDataWebClient overview
b) TXDataWebDataset usage
c) Asynchronous paradigm

17h00 - 17h30
Closing, questions and answers.

Alternative advanced topics that can be handled on-demand:
a) JWT and authentication
b) Server-side events
c) Custom error-handling in server
d) Swagger/OpenAPI

The TMS XData training day price is 295EUR. For Delphi developers attending both the TMS RADical WEB training day and TMS XData training day, price is 395EUR. Contact us directly by email for registrations. Contact us as quickly as possible as registration is on a first-come, first-serve basis.

Bruno Fierens


This blog post has received 2 comments. Add a comment.

Enable HTTPS in your REST server with Free SSL/TLS Certificate from Let’s Encrypt


Thursday, April 19, 2018

One of the most important aspects of a REST API server is security. It should be mandatory that your data is encrypted while being transferred between client and server. And the “standard” way to do such encryption is using HTTP Secure (HTTPS).

To support HTTPS in your server, you need an SSL/TLS certificate. Not so long ago, this was a task that was relatively annoying/hard to do, and it would also require you to pay yearly fees for that. That’s not true anymore, since the release of Let’s Encrypt. From their website: “Let’s Encrypt is a free, automated and open Certificate Authority”. What does that means, basically? You can now have SSL/TLS certificates for free. And automatically!

The purpose of this article is to give you direct step-by-step instructions for you to install your SSL/TLS certificate for any TMS Sparkle-based server (like TMS XData, for example). Thus, if you want more info about Let’s Encrypt and how its system works, please visit their web site to learn more about how it works.

To install a Let’s Encrypt certificate in your TMS Sparkle server, we are going to use a tool named win-acme (Simple ACME Client for Windows, WACS - Windos ACME Simple). It was formerly called letsencrypt-win-simple (LEWS). The video presented at the end of this article was made when the tool still had its old name, so also some screenshots of this article will reflect that as well. But the process remains mostly the same with very small differences mentioned in this article.

In this example we are going to secure a server that responds to address To start with, you must have a domain name and your server must be working and responding HTTP requests to that domain name. Here is for example a screenshot of a browser request to that server. Note that it’s not secure yet

To download win-acme, go to the Releases link of its GitHub page and download the latest version available. By the time this blog post was written the file name should be, but you might find a similar name with a most recent version. In case you want to use the exact version used for this server (to folllow exactly what is being done in the video and in the screenshots) you can download it from this link:

Upload the downloaded file to the Windows server running your TMS Sparkle server, and extract it to any directory, for example C:\letsencrypt. You should have a folder with the files like the following:

Notice the selected file above, named letsencrypt.exe.config. It’s the config file for the tool. In most recent versions, that file would be named settings_default.config. Whatever is the name you have there depending on your version, open that file in a text editor (Notepad, for example) and search for a setting named CertificateStore. Change the value of that setting to “My”. The section of the file should look like this:

<setting name=“CertificateStore” serializeAs=“String”>

In the same folder, create a file named bindcertificate.bat with the following content:

netsh http delete sslcert ipport=
netsh http add sslcert ipport= certhash=%1 certstorename=%2 appid={00112233-4455-6677-8899-AABBCCDDEEFF}

The GUID in appid above could be anything. You can change to a GUID value you want, or just use what's there. You should then have your new file in the folder:

Now open command-line with administrator rights, go to C:\letsencrypt folder if you are not already there, and run the following command. Please don't forget to replace <yourdomain> by your real domain. In the case of our example here, it would be

letsencrypt --plugin manual --manualhost <yourdomain> --validation selfhosting --script "c:\letsencrypt\bindcertificate.bat" --scriptparameters "{5} {3}" --usedefaulttaskuser

Depending on the version of the tool you are using, you might be asked to enter your e-mail address and agree to the terms of condition. The e-mail address will only be used by Let's Encrypt to notify you about certificate expirations. You will only have to do that for the first time.

If everything went ok, you should have an output like this indicating the certificate was generated and installed in your computer:

You can open the MMC Snap-in to check that your certificate is installed properly:

And that's it! Not only the certificate is now installed in your server computer, but it is also configured to your TMS Sparkle server and will be renewed automatically. Your server now supports HTTPS forever! If we browse to our server address now using HTTPS, we can confirm it's using the new certificate:

The following video shows in much more details the operation described above, including using the "test" flag to test the whole process in a test environment before using the production one.

Wagner R. Landgraf


This blog post has received 8 comments. Add a comment.

TMS XData REST Server on Linux - Step by Step - Part 5


Thursday, May 25, 2017

This is part 5 of the tutorial on how to create TMS XData and TMS Sparkle servers on Linux. On Part 4, we have added Sparkle to our Apache module, preparing it to receive any modules we want to add. And in this final part we will add the TMS XData module to it.

Here is video for part 5: Adding the TMS XData module to Apache.

Now that we can add any Sparkle module we want, develop our XData server should be nothing different from when we use Windows. You can find more detailed information about it in other resources (blog posts, our TMS XData documentation, etc.). This tutorial will just cover the basics and deal with some final Linux specific things, like SQLite database permissions.

1. Create a new Aurelius connection for SQLite database

Go to Delphi menu item "File, New, Other...", then "Delphi Projects, TMS Business, TMS Aurelius DB Connection" to open the wizard. Choose "SQLite" for both driver and SQL dialect, and then confirm to create the new connection. Unit name created will be called "ConnectionModule".

2. Add XData Module to Sparkle server

Going back to WebModule1 unit, add the following units to the uses clause:

   {...}, XData.Server.Module, ConnectionModule, Aurelius.Engine.DatabaseManager;

Now remove the Sparkle anonymous module we have added just for testing in previous part 4 of this tutorial, and add the new XData module. Also, let's do a call to TDatabaseManager.Update so our tables and columns are created in the database if needed. The final code of initialization/finalization part of our unit should be like this:

  Server := TWebBrokerServer.Create;
    'http://ubuntu/tms', TSQLiteSQLiteConnection.CreateConnection

3. Define SQLite database location

The two steps above should be enough to get our XData server up and running (yep, only those). But our server connects to a database, and we have chosen to use SQLite. We must then define the location of our SQLite database, and specifically on Linux, we should create and set permissions on it so Apache module can read and write to the database.

Let's go back to the ConnectionModule unit created by the wizard, and change the location of SQLite database by changing the parameter in the TSQLiteSQLiteConnection.CreateConnection function:

class function TSQLiteSQLiteConnection.CreateConnection: IDBConnection;
  Result := TSQLiteNativeConnectionAdapter.Create('/home/user/xdata/xdata.db');

In our example, the SQLite database will be the xdata/xdata.db file in our home folder. You might need to change that location a little bit if you have a different user name on Linux.

4. Create SQLite database on Linux and give proper permissions

Now let's go back to Linux terminal and create the database. Make sure you are in your home directory (you can use "cd" command for that):

mkdir xdata
touch xdata/xdata.db

Now, we need to give Apache access to our database. On Ubuntu, Apache module runs under "www-data" group. This will work here if you are following this tutorial from the very beginning, but it can vary depending on the Linux flavor you are using or other Apache settings. In our case, we will change the group of our xdata folder and all its content to "www-data":

sudo chgrp www-data xdata -R

5. Install SQLite library

Our XData module in Apache will use SQLite to access the database. We must then install SQLite libraries for it to do that. If we were using any other database, like MySQL, PostgreSQL, etc., we would might need to install proper client libraries for them as well. Use the following command to install SQLite library:

sudo apt-get install libsqlite3-dev

6. Rebuild, deploy and restart Apache

All is done. We just have to rebuild our Apache module, deploy it again on Linux, and restart Apache on Linux like we did before in previous parts of this tutorial:

sudo apache2ctl stop
sudo apache2ctl start

And our XData server should be running at root address "http://ubuntu/tms"!

This is the end of this tutorial, I hope it was useful for you. From now on, developing further the XData server is no different than developing for Windows. The video above shows more steps further, like creating an entity in the server and doing some CRUD operations on it.

And of course, for further information on TMS XData, please refer to the XData web page or XData documentation.

Wagner R. Landgraf


This blog post has received 3 comments. Add a comment.

TMS XData REST Server on Linux - Step by Step - Part 4


Wednesday, May 24, 2017

This is part 4 of the tutorial on how to create TMS XData and TMS Sparkle servers on Linux. On Part 3, we have created and deployed our first Apache Module using WebBroker. Now we're going to add TMS Sparkle to it.

Here is video for part 4: Adding TMS Sparkle and using Sparkle modules in the Apache module.

Basically, what we need to do is "wrap" the WebBroker request/response objects into a Sparkle request/response objects. So any Sparkle module can process the requests and provide responses. This part is also described in the documentation, in this page:

1. In WebModuleUnit1 unit, add the units Sparkle.WebBroker.Server and Sparkle.WebBroker.Adapter to the uses clause:

uses {...},
   // just for the anonymous module example
  Sparkle.HttpServer.Module, Sparkle.HttpServer.Context;

2. Declare and create a global TWebBrokerServer instance:

Add a global variable declaration in the unit:

  Server: TWebBrokerServer;

And then create it in initialization:

  Server := TWebBrokerServer.Create;

3. Replace the WebModule1DefaultHandlerAction event handler with the code below to dispatch the requests:

procedure TWebModule1.WebModule1DefaultHandlerAction(Sender: TObject;
  Request: TWebRequest; Response: TWebResponse; var Handled: Boolean);
  Adapter: IWebBrokerAdapter;
  Adapter := TWebBrokerAdapter.Create(Request, Response);

And this should be enough to have TMS Sparkle "plugged" into the Apache module. From now on, you can code just like you do on Windows: create Sparkle modules (like XData), and add them to the server Dispatcher. As a quick example, you could add the following anonymous module to test:
  Server := TWebBrokerServer.Create;
  // add modules you want to use. This example assumes a simple Sparkle module,
  // but you can add your XData, RemoteDB or any other Sparkle module
    procedure(const C: THttpServerContext)
      C.Response.StatusCode := 200;
      C.Response.ContentType := 'text/plain'';
      C.Response.Close(TEncoding.UTF8.GetBytes('Hello from Sparkle!'));

Now you can rebuild the module and deploy to Linux. If you now go to Linux and restart Apache:

sudo apache2ctl stop
sudo apache2ctl start

And refresh the URL in your browser:


You should see a response "Hello from Sparkle!"

In the next part (the final one) we will add the XData module to our Apache module.

Wagner R. Landgraf


This blog post has not received any comments yet. Add a comment.

TMS XData REST Server on Linux - Step by Step - Part 3


Tuesday, May 23, 2017

This is part 3 of the tutorial on how to create TMS XData and TMS Sparkle servers on Linux. On Part 2, we have installed PAServer and launched our first "Hello, World" console application on Linux.

Here is video for part 3: Create and deploy an Apache module to Linux.

We will use WebBroker to create an empty Apache module. But first we need to install Apache on Linux.

1. Install Apache on Linux

On Linux terminal, use the following command to install Apache:

sudo apt-get install apache2

This should be enough to get Apache up and running. You can open your browser on Windows and just try to open the root page (let's consider our host name is "ubuntu" from now on):


And you should get a page from server telling you that Apache is running.

2. Create WebBroker Apache module in Delphi

Going back to Delphi, use menu option "File, New, Open...", then choose "Delphi Projects, WebBroker, Web Server Application".

Check "Linux" option, Next, and then select "Apache dynamic link module". When choosing the module name, type "xdata_module". Of course you can use any name you want, but we will use this name for further configuration in this tutorial. Finish the wizard and you will have the module created.

3. Build and deploy Apache module to Linux

Now build your Apache module (make sure to first select Linux64 platform in Project Manager, otherwise you would be building the module for Win32), and then click "Project, Deploy" menu option to deploy it to Linux. If you still have your PAServer running on Linux, it should send the module file to Linux.

The deployed file location should be something like this:


I might be slightly different in your Linux computer, because you might have used a different user name for Linux user, and a different user name/profile in your Windows machine (the "User-Ubuntu" part). You can simply use WinSCP from Windows to browse your Linux files and discover where is the .so file deployed by PAServer. You should find it by navigating from the PAServer folder created in your home directory.

4. Create Apache configuration files

We must now configure Apache to use our new module. On Linux terminal, go to Apache module configuration folder:

cd /etc/apache2/mods-available

Create two new configuration files:

sudo touch xdata.conf
sudo touch xdata.load

Edit the first file to load module (we will use Nano editor here, if you don't have it installed in your Linux, you can use command "sudo apt-get install nano"):

sudo nano xdata.load

Use the following content for xdata.load file. Here we must use the location where our .so module file was deployed, as we saw in step 3.

LoadModule xdata_module /home/user/PAServer/scratch-dir/User-Ubuntu/mod_xdata/

Press Ctrl+X to save and exit from nano editor, and then let's edit xdata.conf file:

sudo nano xdata.conf

This should be the content of this file:

<Location /tms>
    SetHandler libmod_xdata-handler

Save that file as well, and Apache configuration is finished.

5. Enable Apache module

The configuration files we created are just a module that is "available". We should now enable the module using the following command:

sudo a2enmod xdata

6. Restart Apache

Now we should stop and restart Apache service. Use the following commands for that (we will use such commands very often further in next parts of this tutorial):

sudo apache2ctl stop
sudo apache2ctl start

7. Test Apache module

Now we can go back to Windows, use our browser and go to the following url (remember to change "ubuntu" to the hostname or IP address of your Linux machine, if it's different):


And the browser should display "Web Server Application" as result.

In the next part we will learn how to add TMS Sparkle to the Apache module.

Wagner R. Landgraf


This blog post has received 1 comment. Add a comment.

Previous  |  Next  |  Index