B4J Tutorial [Web] Tutorial - Using MinimaList Controller and Code Snippets

Introduction​

This tutorial is based on MinimaList API Server (version 2.05) on how to use MinimaList Controller library.

For this tutorial, we will cover on using this library for creating API controller.

Update: This tutorial is updated for library version 1.05.

How to install​

Download MinimaListController.jar and MinimaListController.xml from here and paste the files into B4J Additional folder.

Adding a new Controller​

You can open your existing project or start a new MinimaList API Server project.

Right-click on the Controllers group under Modules tab, Add New Module -> Class Module and select MinimaList Controller.

Enter a name for your Controller, eg. ProductController

This will add a ProductController class to the project.

After that we need to register the new controller in ApiHandler class, under Sub ProcessRequest, add the following highlighted code:

Select ControllerElement
    Case "categories"
        Dim Categories As CategoryController
        Categories.Initialize(Request, Response)
        Categories.RouteApi
        Return
    Case "product"
        Dim Product As ProductController
        Product.Initialize(Request, Response)
        Product.Route
        Return
End Select

We need to declare this variable globally in Process_Globals of Main module.

Then we initialize it in ConfigureMinimaList sub.

To load the persisted data from KeyValueStore, add the following code in Sub ConfigureKeyValueStore.

If ProductList.IsInitialized Then
    ProductList.List = KVS.GetDefault("ProductList", ProductList.List)
End If

To allow us to test the new API in API Documentation, we need to add the new controller in Sub ConfigureControllers.

Creating API using Code Snippets​

Type codeget or get to activate the Code Snippet.

Use arrow key down and press Enter (or mouse click) to select the third snippet Code_WebApiUtils_03 Route GET.

The Code Snippet is added.

When the word Controller is on focus, type "Product" and press Enter to replace the Controller placeholder.

Uncomment the FirstIndex and FirstElement variables.

Type get and press Enter to add the first Code Snippet Code_MinimaListUtils_01 Get All Resources.

When the Controller on focus, replace it with "Product". Do the same with MinimaList placeholder to replace with "ProductList" and press Enter.

Add ReturnApiResponse sub if it is not yet added.

Do the similar steps to add GetProduct() sub or skip it for now.

We also use the same steps to create the RoutePost sub.

Type codepost or post to activate the code snippet for Code_WebApiUtils_04 Route POST and press Enter.

Type post again but this time we select the Code Snippet for Code_MinimaListUtils_03 Post Resource to add PostProduct sub.

When the Controller on focus, replace it with "Product". Do the same with MinimaList placeholder to replace with "ProductList" and press Enter.

Finally, uncomment the lines to call RouteGet and RoutePost.

Now navigate to API Documentation / Help to test the new API.

Testing the API​

Let's make a POST call.

You can copy the sample JSON body in the light blue box on the left and paste to the white box in the center.

Click on Submit button and you should see the response.

Checking data is persisted​

Stop the debug.

Run the Debug again and navigate to API Documentation page.

Make a GET call using the first API by clicking on the green Submit button.

If the Response box returns an object, meaning the data is successfully persisted in KeyValueStore.

The data file is name kvs.dat inside Objects folder.

Thanks for following this tutorial.

Regards,
Aeric

 

[aeric]

Update
In MinimaList API Server template v2.06, #plural tag is removed. It is recommended to use plural noun when creating a Controller. e.g ProductsController. To override the controller name in API, use #name tag as comment e.g ' #name = product

Spoiler: #Plural tag is no longer supported

How to use #Plural?

For usual practice, use either only singular or plural is recommended, not both.
Even though it is not a good practice, this API template allows to create a controller with a singular item and a plural with GET method.

E.g.
GET /web/api/v2/items <-- plural, return all items
GET /web/api/v2/item/1 <-- singular, return item corresponding to the id

In Sub ProcessRequest of ApiHandler class, add the plural word together with the singular word. This will call the same controller class.

Select ControllerElement
    Case "item", "items"
        Dim Item As ItemController
        Item.Initialize(Request, Response)
        Item.Route
        Return
End Select

In Sub RouteGet of ItemController, write as following:

' Router for GET request
Private Sub RouteGet
    Select Version
        Case "v2"
            Select ElementLastIndex
                Case ControllerIndex
                    Dim ControllerElement As String = Elements(ControllerIndex)
                    Select ControllerElement
                        Case "items"
                            GetItem
                            Return
                    End Select
                Case FirstIndex
                    Dim FirstElement As String = Elements(FirstIndex)
                    If Utility.CheckInteger(FirstElement) = False Then
                        Utility.ReturnErrorUnprocessableEntity(Response)
                        Return
                    End If
                    GetOneItem(FirstElement)
                    Return
            End Select
    End Select
    Utility.ReturnBadRequest(Response)
End Sub

Remember to add #Plural as comment

Private Sub GetItem
    ' #Plural = items
    ' #Version = v2
    ' #Desc = Read all Items in MimimaList
    HRM.ResponseData = Main.MinimaItem.List
    HRM.ResponseCode = 200
    If Main.SimpleResponse Then
        Utility.ReturnSimpleHttpResponse(HRM, "List", Response)
    Else
        Utility.ReturnHttpResponse(HRM, Response)
    End If
End Sub

Edit:
If your controller is in plural form and you want to use singular route, you can use the #Plural comment to overwrite it.