B4J Tutorial Web API Server (v3)

aeric · Tuesday at 2:45 PM

Introduction
This tutorial is based on [Project Template] Web API Server 3.

Installation

Download and save Web API Server (3.00).b4xtemplate file into B4J Additional Libraries folder.
You also need to download WebApiUtils.b4xlib (v3.02) and save inside the same folder.
It is recommended to use this template with MiniORMUtils.b4xlib (v1.14) which is a dependency by default.
You can put this library inside B4X Additional Libraries folder since it is a cross platform library.
Note: You can also use MinimaListUtils library or write your own SQL code using jSQL library.
By default the template is based on SQLite database as backend.
Therefore you need sqlite-jdbc driver in your B4J or B4X Additional Libraries folder. B4J comes with sqlite-jdbc-3.7.2 as Internal Library.
If you want to use MySQL database, you need to use MySQL jdbc driver and put inside B4J Additional Libraries folder. e.g mysql-connector-java-5.1.49

Create Project

Once all the required libraries and template are in place, you can start B4J IDE.
Select from File menu, New, Web API Server (3.x)
Enter the name of your project as you like. Then click OK.
Now the project is ready to run as it is.

Running the Project

Click menu Project, Compile & Run (F5) or the play button on the toolbar.
Hover you mouse pointer to the AppStart sub and click on the highlighted link to open the app on your web browser.
The browser will open and load the index page.
It is a CRUD web application where you can add a new product (C), search for a product (R), edit an existing product (U) and delete a product (D).
It has already generated some common APIs following the RESTful API principal.
To see the list of APIs, click the API link with a gear icon on top navigation bar.
You will be redirected to the API documentation page.
You will see there are endpoints such as GET, POST, PUT and DELETE which are represented in different colours.
You can click on any item to expand the section.

Perform Tests

GET

Let's try to perform our first GET request with an id parameter.
Click on the second end point labeled GET /api/categories/:id
Edit the Path by replacing the :id parameter with 2 and click on the green Submit button.
The form will send an AJAX request to the API server and return a JSON response (Code 200 for Success).

POST

To test a POST end point, click the third item with labeled POST /api/categories.
Copy the sample format from the left and paste in the Body textarea.
Edit the content, i.e value of the category name in the illustration and click the yellow Submit button.
You may follow the convention to return code 201 Created for new item added to the resource.
For this demo, it is set to return a simple response and it doesn't support text Created but display success as default text.
You need to set Simple Response to False in server configuration to return code 201 response for your client apps.

This is the end of tutorial for now. Thanks for taking your time to read it.

I will update this tutorial again from time to time.

Please do not post any question on this thread.

Always start a new question with the name Web API Server 3 or post your question here : [Q&A] Web Api Server 3

aeric · Wednesday at 7:27 AM

Part #2: Configure Settings

B4J generate a config.ini when you compile the project for the first time in Debug (or Release) mode.
You can open the file using Notepad or any Text Editor.
After you made any changes, you need to compile the project again for the settings to take effect.

B4X:

# Define App Constants
HOME_TITLE=WEB API SERVER
APP_TITLE=Web API Server
APP_TRADEMARK=B4X
APP_COPYRIGHT=Copyright Computerise System Solutions 2024

You can edit these settings.
It will applies to the text displayed on the front-end and API documentation page.
Similar to config.properties, the values does not support UTF8. You may want to set text for non-English characters in the code.

B4X:

# Server Path
ROOT_URL=http://127.0.0.1
ROOT_PATH=
API_NAME=api
API_VERSIONING=False

ROOT_URL (default=http://127.0.0.1) is for setting the server URL. You can edit to your domain name in production release.
Note: It seems Chrome is no longer allowed http://localhost so it is better to stick with http://127.0.0.1 during development.
ROOT_PATH (default=<empty>) can be set to other name e.g /web
API_NAME (default=api) is better to leave as default. You need to change the values in code, html templates and JavaScript files if you edit it.
API_VERSIONING (default=False) can be set to e.g /v1 or /preprod

B4X:

# Java server port
ServerPort=8080
SSLPort=0

It is important to set the correct number for B4J server port.
Make sure the port number is not used by another service or blocked by the firewall.
You can set the port e.g 80
It is recommended to use SSL protocol in production. If SSLPort number is set to 0, SSL is disabled.
You can set it to e.g 443

B4X:

# SSL Keystores
# Generate a keystore from Windows CMD
# C:\Java\jdk-11.0.1\bin\keytool -keystore keystore -alias jetty -genkey -keyalg RSA
# Copy keystore file to Objects folder of the B4J project
SSL_KEYSTORE_DIR=/etc/letsencrypt/live/mydomain.com
SSL_KEYSTORE_FILE=keystore
SSL_KEYSTORE_PASSWORD=xxxxxxxxx

If SSLPort is not set to 0 (enabled), you need to set the keystore settings.
During development, you can use CMD to call keytool in the JDK to generate a self sign keystore file.
Put this file in Objects folder and leave the SSL_KEYSTORE_DIR setting as <empty>.
During production, you can use a real certificate or generate one using LetsEncrypt.

B4X:

# DATABASE CONFIGURATION

## SQLite configuration:
DbType=SQLite
DbFile=webapi3.db
DbDir=
DriverClass=org.sqlite.JDBC
JdbcUrl=jdbc:sqlite:{DbDir}/{DbFile}

SQLite is set as default DbType.
You can change the DbFile as you like e.g server.sqlite
You can leave DbDir as <empty> to store the file inside Objects directory.
If you want to save the file in a different location, you need to set it using forward slash or escape character e.g C:/server/db or C:\\server\\db
It is recommended to leave the values for DbType, DriverClass and JdbcUrl as default.

If you want to use MySQL as backend database, uncomment the settings like the following example.

B4X:

## MySQL configuration:
DbType=MySQL
DbName=webapi3
DbHost=localhost
DbPort=
DriverClass=com.mysql.cj.jdbc.Driver
JdbcUrl=jdbc:mysql://{DbHost}:{DbPort}/{DbName}?characterEncoding=utf8&useSSL=false
User=root
Password=password
MaxPoolSize=100

You can leave DbPort as <empty> if MySQL is running on default port 3306.
You can edit the DbName, User, Password, MaxPoolSize or other settings according to your needs.

This is the end of tutorial for Part #2. Thanks for taking your time to read it.

Always start a new question with the name Web API Server 3 if you have any question on this tutorial.

aeric · Wednesday at 8:07 AM

Part #3: How Does the Project Work?

First thing to know, this is a B4J server app. Therefore, it depends on the B4J Server library.
You also need to understand, it is a non-UI or console app. It doesn't have native UI library or component.
You can't add any B4J library that depends on XUI or jFX.
After the project is compiled as Release, you can run the binary file on Windows CMD or Terminal on Linux.
To host the server app, it is recommended to find a VPS that you have full access to run the binary using a remote SSH terminal.
You also need to have a JDK on the server for you to call the .jar file.
It is recommended that you put the compiled binary file e.g server.jar, together with the www directory inside a location that you have write permission.
The server will have to write it's access log and database file if you are using SQLite to keep inside the location same as the binary file.
You also need to make sure the server can read the config.ini file and contents inside www directory.
You can follow the tutorials on this forum about running B4J Server.

Starting the Server

To start the server, you Initialize the object as global in Main module and call the method Start.
We should configure the settings before we start the server.
The default server port number for B4J server is 8080.
We can change this setting using InitServer sub in the Main module.

Initializing Server Configuration

In this project, we use config.ini to make changes to the server configuration without needing to recompile the project.
The settings in config.ini has been explained in the previous tutorial.
This project has embedded with a config.example file in the assets or Files directory.
If you have deleted the config.ini file, a new config.ini file will be copied from the example template.
InitServer sub will read config.ini file for the configuration settings.
All the configuration will be assigned to a Map object name ctx where it can be read from anywhere of the project and also use by HTML template engine, such as for displaying the title label and version number.

EnableCORS

This setting must be enabled to allow another application (from different origin) to access our API especially when using JavaScript.
If you have another web app hosted with different port number e.g Vue app running on port 3000 and this server is running on port 8000 then you need to enable CORS or otherwise you will get errors in web browser.
You can disable this setting if you are sure there are no other application sharing the API.
This is not applied to mobile or desktop native client apps want to access the API.

EnableSSL

This setting is recommended to be set to True during production to protect the data transfer being encrypted between the server and client.
As explained in previous tutorial, you need to configure the SSLPort to number other than 0 and provide information of the keystore.

EnableHelp

Basically this setting is use to hide the API documentation link to be visible to the end user.
You can also use Conditional symbol to add or disable the HelpHandler during production.

SimpleResponse

This setting allows you to choose the API output in different JSON format.
By default, it is not enabled.
This means the output of the JSON Response follows a predefined the structure as set inside ReturnHttpResponse sub of WebApiUtils library.
Learn more about SimpleResponse in tutorial part #5.

StaticFilesFolder

Usually the static files folder is set as www inside Objects during development.
It is recommended to leave the folder name as www or you may want to change as public.
After compiled as Release, it will become the same level as the jar file.

StaticFilesBrowsable

You may want to restrict the client to list the contents of your www assets directory from the browser.

You can set StaticFilesBrowsable to False which is by default also set as False.

B4X:

Config.StaticFilesFolder = File.Combine(File.DirApp, "www")
Config.StaticFilesBrowsable = False

Version

The VERSION_NAME is set in Process_Globals which is just for displaying purpose in front end and terminal log as "welcome message".
B4X:
```
Config.Version = VERSION_NAME
```

Applying Server Configuration

The ApplySettings sub will take care of applying the settings if you have override any inside InitServer sub.
You must not modify any code inside ApplySettings sub.

Initializing Database Configuration

The InitDatabase sub will take care of applying the settings read from the config.ini file.
You must not modify any code inside InitDatabase sub.

Connecting to the Database

Based on the Build Configuration that you selected, the project is connecting to SQLite by default.
You need to select MySQL from the dropdown list if you want to use MySQL database.
CreateConnection sub will take care of applying the settings and attempt to connect to the database.
It will also check if database is exist or else call CreateDatabase sub.

Creating the Demo Database

If no database is present, the CreateDatabase sub will create a new database, generate the tables and insert some dummy data.
As this template is using MiniORMUtils library, the same code is use to accomplish this task, regardless of whether you choose SQLite or MySQL.
The SQL queries are handled internally by the library despite the differences between the 2 databases.
You may want to learn about using MiniORMUtils in another tutorial or post a new question on this library.

Configure Cross Origin (CORS)

If you have set Config.EnableCORS = True, then you may want to configure the Cross Origin settings on this server accessed from another origin or server inside the ConfigureCORS sub.
This is the case when you have another application that is using JavaScripts to make API calls to this server.

By default, there is already an example added for you.

B4X:

Paths.Add(CreateMap("path": "/api/*", "origins": "http://localhost, http://127.0.0.1:3000", "methods": "POST,PUT,DELETE", "headers": "*"))

This mean you are allowing another application specified in the list of "origins" to access our /api "path" and its derivatives using the "methods" POST, PUT and DELETE.

Configure SSL for the Server

The ConfigureSSL sub will take care of setting up the SSL. You must not change any code in this sub.
This sub will display some messages in the Logs depending on the settings for EnableSSL and the settings in config.ini file.

Configure Static Files

The ConfigureStaticFiles sub will take care of setting up the directory name and browse permission of static file folder. You must not change any code in this sub.

Switching of Database

If you have decided to switch to another database by selecting a different item from the Build Configurations dropdown list, make sure you have commented the SQLite configuration explained in the previous tutorial Part #2.
If the configuration does not match, the ShowBuildConfigurationNotMatch sub will display a warning message and the application will be terminated immediately.

Commonly Use Subs

You can add extra subs to the Main module so they are reusable in any of the server handler classes.
There are 3 subs added for you for communicating with the database.

Note that DBConnector is part of the MiniORMUtils library.

B4X:

Public Sub DBEngine As String
    Return DBConnector.DBEngine
End Sub

Public Sub DBOpen As SQL
    Return DBConnector.DBOpen
End Sub

Public Sub DBClose
    DBConnector.DBClose
End Sub

This is the end of tutorial for Part #3. Thanks for taking your time to read it.

Always start a new question with the name Web API Server 3 if you have any question on this tutorial.

aeric · Wednesday at 8:10 AM

Part #4: Server Handlers

There are 4 types of Class for writing code in B4J.

Standard Class
Server Filter
Server Handler
Server WebSocket

In this tutorial, we will focus on Server Handler.
This is the class that we use most of the time to write all of the business logic for the API.

Conventions

For this Web API Server template, we use the following naming convention to differentiate the purpose of the handler class.
- Api Handler - to read the Request from the URI contains the path /api and output the Response as JSON
- Web Handler - to read the Request from the URI without the /api path and output the Response as HTML
For e.g there are 2 handlers for Categories i.e CategoriesApiHandler and CategoriesWebHandler.
You can either have Api handler and/or Web handler.
As you can guess, CategoriesApiHandler is use for taking care of the API endpoints for Categories while CategoriesWebHandler is use to display the web page to manage the Categories.
IndexWebHandler is use to display the index page when a user browse to the root path.
The index page calls the API endpoints from ProductsApiHandler and FindApiHandler.
HelpHandler is use to display the API documentation page. It will be use to call any API endpoint that you have created.
Each Web handler is linked to its respective JavaScript file to make AJAX calls and process the returned JSON Response from an Api handler.

To be continued...

aeric · Wednesday at 10:35 AM

Part #5: SimpleResponse

SimpleResponse.Enable = False

By default, a predefined structure is return when using ReturnHttpResponse sub of WebApiUtils to output the JSON response.

I recommend to use the default because it covers the response status code, message and error message without the need to worry whether the response should be an array or object. The response data is always returned as an array (list).
Here is an example of the output:

JSON:

{
  "a": 200,
  "r": [
    {
      "deleted_date": null,
      "category_id": 2,
      "id": 3,
      "product_price": 1000,
      "created_date": "2024-10-30 08:33:13",
      "product_code": "T002",
      "modified_date": null,
      "product_name": "Optimus Prime"
    }
  ],
  "s": "ok",
  "e": null,
  "m": "Success"
}

You won't notice this format in API documentation because only the response 'r' item is show. A small label is display below the response box results from the combination of 'a' and 'm' / 'e' items.

For details, you can check the JavaScript code of help.js file inside scripts folder of www/assets.

JavaScript:

success: function (data) {
    if (data.s == "ok" || data.s == "success") {
        var content = JSON.stringify(data.r, undefined, 2)
        $("#response" + id).val(content)
        $("#alert" + id).html(data.a + ' ' + data.m)
        $("#alert" + id).removeClass("alert-danger")
        $("#alert" + id).addClass("alert-success")
        $("#alert" + id).fadeIn()
    }
    else {
        var content = JSON.stringify(data.r, undefined, 2)
        $("#response" + id).val(content)
        $("#alert" + id).html(data.a + ' ' + data.e)
        $("#alert" + id).removeClass("alert-success")
        $("#alert" + id).addClass("alert-danger")
        $("#alert" + id).fadeIn()
    }
}

SimpleResponse.Enable = True

You will notice in this version, the setting is set to True inside the code.
B4X:
```
Config.SimpleResponse.Enable = True
```
Note: You can comment the code if you want.
This is the case where you want to create API that follow the structure you want.

When this setting is set to True, the JSON format as showed above is now show with just the 'r' part, exactly as what you see in the Response text area in API documentation page.

JSON:

{
    "deleted_date": null,
    "category_id": 2,
    "id": 3,
    "product_price": 1000,
    "created_date": "2024-10-30 08:33:13",
    "product_code": "T002",
    "modified_date": null,
    "product_name": "Optimus Prime"
}

You can actually compare the difference by viewing the actual output by pasting the API end point to the browser address.
Take note that you can only see the output for GET request in browser.

Debugging using Developer Tools

We can use the Developer Tool in web browser for debugging the API response.
First we need to write console.log() inside the JavaScript for AJAX call.
This is useful for debugging other methods such as POST, PUT and DELETE.
When Config.SimpleResponse.Enable = True, the response is in simple format.
The page for API documentation will load help.simple.js file to make AJAX calls.
Open help.simple.js using a Text Editor and add the following code at line #88.
console.log(data)

The code will look like the following:

JavaScript:

case element.hasClass("get"):
    return {
        type: "GET",
        headers: headers,
        success: function (data, textStatus, xhr) {
            console.log(data)
            var content = JSON.stringify(data, undefined, 2)
            $("#response" + id).val(content)
            $("#alert" + id).html(xhr.status + ' ' + textStatus)
            $("#alert" + id).removeClass("alert-danger")
            $("#alert" + id).addClass("alert-success")
            $("#alert" + id).fadeIn()
        },
        error: function (xhr, textStatus, errorThrown) {
            var content = xhr.responseText
            $("#response" + id).val(content)
            $("#alert" + id).html(xhr.status + ' ' + errorThrown)
            $("#alert" + id).removeClass("alert-success")
            $("#alert" + id).addClass("alert-danger")
            $("#alert" + id).fadeIn()
        }
    }
    break

After changes is saved, you need to refresh the JavaScript source by right clicking on the page and choose view page source (Ctrl+U).
Scroll down to the bottom of the page until you see
<script src="http://127.0.0.1:8080/assets/scripts/help.simple.js"></script>
Click on the link to open it on a new tab and right-click Reload (Ctrl+R).
Open the Dev Tools by right clicking on the page (on Google Chrome) and choose Inspect (usually you need to scroll to bottom of the pop up menu) or just press combo keys of Ctrl+Shift+I.
The Dev Tools panel will appear. Usually it is focusing on the Console tab. Otherwise you need to click on the Console tab.
Now try to make a new GET request.
You should see an arrow with text Object appeared and on the left showing 1 user message.
On the right you see the name of the JavaScript file colon the line number on the code that produce the message log.

View attachment 158139
Click the Object to expand it. You can see the content of the JSON object return from the API.

View attachment 158140
If it is not working, probably you need to restart the server. Stop the debug and click run again. Then try again.
The default JSON Format for SimpleResponse is "Auto".
You can change the Format by setting it to "Map" to return as object (or "List" to return as array) for all the API responses.
View attachment 158142
By changing it to Map, you need to specify the key of the "Map" using the DataKey property.
If you don't specify a key name, it will use "data" as the default key.
B4X:
```
Config.SimpleResponse.Initialize
Config.SimpleResponse.Enable = True
Config.SimpleResponse.Format = "Map"
Config.SimpleResponse.DataKey = "result"
```
After made this changes, now try to restart the debug (F11) and see the difference of output but this time we test on the API end point that should return an array (list) which is the /api/products end point.

View attachment 158143
So you see the response is now return as object (wrapped in curly brackets) instead as an array (wrapped in square brackets) and it is using the key that we specified.

Conclusion

There are 4 types of output for SimpleResponse:

SimpleResponse.Enable =	False	\|	Format=	(Fixed)	\|	Return data=	object with r data always an array
SimpleResponse.Enable =	True	\|	Format=	Auto (default)	\|	Return data=	depends whether we initialize object or data
SimpleResponse.Enable =	True	\|	Format=	Map	\|	Return data=	always as object (with optional customize key name)
SimpleResponse.Enable =	True	\|	Format=	List	\|	Return data=	always as array

It depends on your use case which type is suitable.
You can build more complex JSON response by nesting the objects and arrays.

This is the end of tutorial for Part #5. Thanks for taking your time to read it.

Always start a new question with the name Web API Server 3 if you have any question on this tutorial.

aeric · 2024-11-01T07:20:09+0000

Part #6: Add Boilerplate Code Using Code Snippets

coming soon...

B4J Tutorial Web API Server (v3)

aeric

Expert

aeric

Expert

Attachments

aeric

Expert

aeric

Expert

aeric

Expert

Similar Threads

B4J Tutorial Web API Server (v3)

aeric

Expert

aeric

Expert

Attachments

aeric

Expert

aeric

Expert

aeric

Expert

Similar Threads

Privacy & Transparency

Privacy & Transparency