In this RAD Server CRUD Procedures – Part 3 post we will show how to implement a FireMonkey (FMX) Client to call the RAD Server CRUD procedures and interact with the Employee Table.
In the part 2 post, we discussed modifying the default generated CRUD procedure implementations from the RAD Server Package Wizard, to show one possible way to implement Get, GetItem, Post, Put and Delete.
In the part 1 post, we discussed the the default generated CRUD procedure implementations from the RAD Server Package Wizard.
The Embarcadero RAD Server (also known as EMS – Enterprise Mobility Server) uses the industry standards of REST, and to transfer data to and from the RAD Server REST Service, JSON – JavaScript Object Notation, is typically used as the transfer encoding.
Due to the Embarcadero RAD Server supporting industry standard REST and JSON, we will use Delphi’s, C++ Builder and/or RAD Studio’s REST Client Library components (TRESTClient, TRESTRequest, and TRESTResponse ) to implement our EMS REST Client.
And recall from Post 2, we used the System.JSON Classes (TJSONArray and TJSONObject) on the back-end RAD Server to implement our CRUD procedures.
Employees REST Client
For our main REST Client UI form, we have all of the ten (10) columns (fields) from our Employee Table, mostly as TEdit controls for First Name, Last Name, etc., and TSpinBox for the Employee Number, Department Number, and Salary, and one TDateEdit for the HireDate:
The bottom panel has 10 TButtons. These buttons will perform the following functions from our RAD Server CRUD procedures:
READ: performs the REST HTTP GET, to return all records from the Employee table.
PREV: Displays the previous record.
NEXT: Displays the next record.
FIRST: Displays the first record.
LAST: Displays the last record.
CREATE: Starts the create mode, to allow the user to use the form to enter a new record.
COMMIT: The commit button gets enabled by the CREATE button, and this COMMIT button makes the REST HTTP POST call to the RAD Server to INSERT a new record into the Employee table.
EDIT: Starts the Edit mode for the UI form, similar to how Create enter a create mode, allow the user to edit a record.
UPDATE: The update button gets enabled by the EDIT button, and after we have made edits to the record, this Update button makes the REST HTTP PUT call to the RAD Server to UPDATE this existing record in the Employee table.
DELETE: This Delete button, let’s us delete the current EMP_NO from the Employee table, by making the REST HTTP DELETE call to the RAD Server to DELETE this EMP_NO from the Employee table.
With the COMMIT and UPDATE buttons, we do perform their REST calls, and then we perform another GET (READ) call, to get all of the records again. This was just done just for simplicity reasons.
This REST Client application also uses the REST Client Library components; RESTClient, RESTRequest and RESTResponse:
The Embarcadero REST Client Library is a framework for accessing REST-based web services, like the Embarcadero RAD (EMS) Server. The library is available for all platforms that are supported by Delphi and/or C++ Builder The REST Client Library framework focuses on JSON as the representation format.
Let’s now take a look at the implementation code for this Employees REST Client.
READ (GET)
The source code for the READ (Get) button is this:
[crayon-673fb086a0f3c199549605/]
What we are doing in this code for the READ is:
1. We are creating a REST request.
2. The resource on the RAD Server that we want is ‘employees‘ . So we set the Resource property of the TRestRequest to ‘employees‘ ( RESTRequest.Resource := ’employees’; )
3. Next we set the Method property of the TRestRequest to Get ( RESTRequest.Method := TRESTRequestMethod.rmGet; ).
4. Then we set the Response component, to receive the data back from the request ( RESTRequest.Response := RESTResponse; )
5. The Request and Response components from the REST Client Library, are TRestRequest and TRestResponse, that we placed on the main UI form. At run-time we modify their properties as needed.
6. The other REST Client Library component is the REST Client (TRestClient), also added to the main UI form. The TRestCient represents your HTTP Client. So, what you do with these REST Client Library components is:
6a. Using the Object Inspector, for the TRestClient, set the BaseURL to the IP address and Port of your running RAD Server. In my case it’s http://127.0.0.1/8080 The loopback address on port 8080:
6b. for the TRestRequest, set the Resource to what you wish to use. In my case it’s the ‘employees‘ resource. And you also set its Response property to a Response component. In my case, to RESTResponse, to receive the data back from the server:
6c. If we look at the Content property on the TRestResponse, we see that it’s value is empty.
6d. Run the RAD Server Development Server we created from the Part 2 post:
6d. Right-click on the TRestResponse component and select Execute, we get a Response 200-OK :
This executed the request for the Employees data. So, now if you look at the response in the Content property of the TRestResponse, the content now has our Employee records, as a JSON Array:
So we used these REST Client Library visual components to create a connection to the RAD Server, and then in the code, at run-time, we modify the parameters, for the needed resource, HTTP Method, and correct Response.
7. Next, we execute the Request: ( RESTRequest.Execute; ).
8. Next, we decode the response we get back from the request. Now, recall, from the part 2 post, that the response will be a JSON Array containing all of the Employee table records, for the READ (Get) procedure: fJSONArray := TJSONObject.ParseJSONValue(RESTResponse.Content) as TJSONArray;
9. So we decode all the employee records into a TJSONArray which is at global scope:
[crayon-673fb086a0f47242340249/]
fJSONArray: TJSONArray, which is a private member of my class that is going to contain all of the employee data.
10. Next, we call this JSONToForm procedure:
[crayon-673fb086a0f4a732428201/]
This JSONToForm procedure loops through the fJSONArray, and copies the values from that array to the various edit controls on the form. Another option would be to use Live Bindings to bind the data to the controls, but this JSONToForm procedure is a manual way of doing this.
Live Bindings was introduced in Delphi, C++ Builder, RAD Studio XE3 primarily as a way to link FireMonkey Controls (that don’t use the TDataSource model) to data, but also allow any object to be bound to and shown visually.
Testing FMX REST Client READ procedure
1. With the RAD Server running, start the Employees Client, click the READ button, you should see the Employee data displayed on the UI form, like this:
2. And on the Log on the RAD Development Server, you should see the Request for ’employees’ Resource, with the GET Endpoint, using the Get HTTP Method, like this:
NEXT button
To display the next record in the JSON array(fJSONArray), we implemented with this code:
[crayon-673fb086a0f4b353889675/]
Prev Button
To display the previous record in the JSON array (fJSONArray), we implemented with this code:
[crayon-673fb086a0f4d269933944/]
First Button
To display the first record in the JSON array (fJSONArray), we implemented with this code:
[crayon-673fb086a0f4f769626496/]
Last Button
To display the last record in the JSON array (fJSONArray), we implemented with this code:
[crayon-673fb086a0f50532328720/]
Create button
The Create button sets the UI into create mode, allowing the user to use the form to enter a new record. Clicking the Create button executes this code:
[crayon-673fb086a0f51323468511/]
This OnClick Event for the Create button click code with the ClearForm procedure clears the form and adjusts the text read-only and prompts:
[crayon-673fb086a0f53435389303/]
And the CreateMode procedure, sets the columns Read Only values, default text prompts, font colors for the various edit fields, and disables all the button, except the Commit button, with this code:
[crayon-673fb086a0f54461655679/]
And displays the UI in create mode, like this:
The user can now enter a new employee record on this Create Form:
And click the COMMIT button, to POST (CREATE) the new Employee record. The OnClick Event for the COMMIT button executes this code:
[crayon-673fb086a0f56450298668/]
The above btnCommitClick procedure performs these steps:
1. Resets the UI back to the first EMP_NO.
2. If you click the LAST button, we see that our new Jane Smith employee has been INSERTED into the Employee table with its auto-generated Employee Number = 148.
3. The COMMIT button makes the REST Client Library request:
[crayon-673fb086a0f57045673072/]
3a. We set the Resource property of the RESTRequest to our Resource Name on the RAD Server, which is ‘employees‘.
3b. Next we set the HTTP Method to POST, because we want to create a new record.
3c. Then we set the Response component, to receive the data back from the request ( RESTRequest.Response := RESTResponse; )
4. Next, we clear out the Body of the Request ( RESTRequest.Body.ClearBody; ),
5. And then we start adding as JSON data, all of the parameters that we want from the form:
[crayon-673fb086a0f59767706283/]
6. We are adding these as PropertyName and PropertyValue, to write into a JSONWriter.
7. We then set the Form into BROWSE mode by called this BrowseMode procedure, that sets the edit controls on the form for read-only, text prompts, text color, and enables all the buttons, except the Commit and Update buttons.
8. After we are in Browse Mode, then after we execute the Request ( RESTRequest.Execute; ) we will be able to read the data, since the data will be in read-only mode.
9. Lastly, we execute the READ button ( btnReadClick(Sender); ) to just re-read the data from the database.
Update (Put) button
Next let’s look at the implementation of the Update (Put) button.
The Edit and Update buttons are implemented similar to the Create and Commit buttons we just discussed above.
1. Looking at this OnClick Event procedure code for the Update button:
[crayon-673fb086a0f5b758480210/]
2. We see we are also making a REST Client Library request:
[crayon-673fb086a0f5c621519476/]
2a. Where the Resource is ’employees’ with the specific EmployeeNumber we want to Update.
2b. Then for the HTTP Method we use PUT, since we will be UPDATEing this one specific record.
2c. And then we set the Response component, to receive the data back from the request ( RESTRequest.Response := RESTResponse; )
And the remainder of the implementation is the same as the Create button implementation, where we populate the JSON resource to post (update).
Testing Update (Put) Procedure
Let’s test the Update (Put) on the last Jane Smith, EmployeeNumber = 148 that we Created in the employee table:
1. With the RAD Development Server running.
2. Click the READ Button.
3. Click the LAST Button.
4. This should display our last Jane Smith, EmployeeNumber = 148 that we Created in the employee table:
5. Click the EDIT Button. The Edit Button implements this code allowing you to edit the Edit boxes:
[crayon-673fb086a0f5e973861409/]
Where the EditMode procedure is implemented with this code:
[crayon-673fb086a0f5f124490668/]
6. This puts the UI form into EDIT mode, with the Update (Put) button enabled, allowing the user to modify this one Jane Smith, EmployeeNumber = 148 record:
7. Let’s say Jane get’s married and changes her last name from Smith to Doe. Change the LastName Edit box to Doe:
8. Click Update button.
9.We see that the RAD Server Log shows:
[crayon-673fb086a0f61228033733/]
9a. The Request for the ’employees’ resource, calling the PutItem endpoint, using the HTTP Method for PUT.
9b. And this is followed by the RAD Server Request again for the ’employees’ resource, calling the Get endpoint, using the HTTP Method for Get. And this is for the Re-read of the data ( btnReadClick(Sender); )
10. If you now click the LAST button, we should see that the LastName for EmployeeNumber 148, has been Updated to ‘Doe’ from ‘Smith’:
Delete (Delete) Button
1. Lastly, looking at the implementation of the Delete button:
[crayon-673fb086a0f63487711349/]
2. What we are doing in this Delete implementation is once again making a REST Client Library request:
[crayon-673fb086a0f64351835075/]
2a. Where the Resource is the ’employees’ with the one specific EmployeeNumber we want to delete. For example, if we want to delete Employee Number 146, we set the Resource to ’employees/146′.
2b. Then for the HTTP Method we use Delete, since we will be DELETEing this one specific record from the employee table.
2c. And then we set the Response component, to receive the data back from the request ( RESTRequest.Response := RESTResponse; )
3. We then execute the Request ( RESTRequest.Execute; )
4. And finally we re-read the data back ( btnReadClick(Sender); )
Testing DELETE (Delete) Procedure
1. Let’s Delete the Last record, which should be the Jane Doe, EmployeeNumber = 148 record, that we just Updated.
2. With EmployeeNumber = 148 record displaying on the Employees Client, click the DELETE button.
3. On the RAD Server Log, we see
{“Thread”:3680,“Request”:{“Resource”:”employees”,“Endpoint”:”DeleteItem”,”Method”:”DELETE”,“User”:”(blank)”,”Time”:”6/18/2021 1:13:21 PM”}}
{“Thread”:11524,”Request”:{“Resource”:”employees”,”Endpoint”:”Get”,”Method”:”GET”,”User”:”(blank)”,”Time”:”6/18/2021 1:13:21 PM”}}
Telling us that we have made a Request for the ’employees’ resource on the RAD Server, called the DeleteItem endpoint, using the HTTP Method Delete.
The Delphi and C++ Builder project source code for this Employees REST Client can be downloaded here:
Delphi Employees REST Client
C++ Builder Employees REST Client
In conclusion, these three posts on RAD Server CRUD Procedures showed one way to build REST Services using RAD Server using the System.JSON classes and REST Clients using the REST Client Library. Consider using these sample Server and Client project application code as template code for implementing CRUD Procedures (CREATE, READ, UPDATE and DELETE) using RAD Server!