B4J Library [Web] WebApiUtils

Version : 6.99 (last version)
A utility class to simplify the development for server app using project template Pakai Server v6 (f.k.a. Web API Server).

GitHub:
https://github.com/pyhoon/WebApiUtils-B4J

HelpHandler, the API Documentation class is now included as a class template.
It depends on MiniHtml2, MiniCSS and MiniJS.
The HelpHandler is now using Bootstrap 5, HTMX and AlpineJS for the frontend.
Alternatively, a swagger-ui can be added to Pakai Server project.

Files:

• swagger.zip
• WebApiUtils.b4xlib

Depends on:

• JavaObject
• Json
• jStringUtils
• Xml2Map

Please report bugs if you found any or start a new thread for any question.

 

[aeric]

Version: 4.00

What's New

• SimpleResponse removed
• VerboseMode as new property, when value is True, the response json returns array or object (formerly only array)
• Updated Code Snippets

Migration:

1. VerboseMode is opposite of SimpleResponse.Enable (version 3)
   [CODE lang="b4x" highlight="5"]Private Sub Configurable
   conf.EnableHelp = True
   conf.EnableSSL = True
   conf.EnableCORS = True
   conf.VerboseMode = True
   conf.StaticFilesBrowsable = False
   End Sub[/CODE]
2. To initialize API Handler
   [CODE lang="b4x" highlight="3"]Public Sub Initialize
   HRM.Initialize
   HRM.VerboseMode = Main.conf.VerboseMode
   End Sub[/CODE]

 

[aeric]

Version: 4.10

What's New

• XML format API is finally available
• ReturnHttpResponse2 (Private)
• Custom root (default is <content>) and result element (default is <result>)

To generate XML format API, initialize the handler like following:
[CODE lang="b4x" highlight="4"]Public Sub Initialize
HRM.Initialize
HRM.VerboseMode = Main.conf.VerboseMode
HRM.ContentType = WebApiUtils.CONTENT_TYPE_XML
End Sub[/CODE]
Note: Verbose mode works for both JSON and XML.

 

[aeric]

Version: 4.20

What's New

• Added RequestDataJson sub (RequestData sub is now just a reference to this sub)
• Update Api Handler.txt snippet

 

[aeric]

Github version control messed up.
Fixing up.

 

[aeric]

Version: 4.30

What's New

• Too much addition +1224 and deletion -480
• Many code are still under experimental
• This is a preparation to enable Web API Server v4 to generate JSON and XML format API with ordered keys structure (for viewing purpose)
• This also will promise more flexible custom keys for JSON verbose mode instead of using the meaningless a-r-s-e-m keys

So whether you are feeling s-e-r-a-m to "pakai" the new Web API Server v4 or is it really feel m-e-s-r-a to you,
you may able to customize the keys as you like and become the s-m-a-r-t , m-a-s-t-e-r or s-t-a-r !
You are no longer limited to get the a-r-s-e-m format in Web API Server v3.
You can even change the keys with combination of "status", "code", "message", "error", "type", "results" or part of them.

This is the most important feature for the upcoming Web API Server v4 using WebApiUtils v4.
Don't forget MiniORMUtils library is getting more powerful and flexible, which has enabled this to happen !

VS

Footnote:
In Malaysian language,
seram means scary
mesra means friendly
pakai means wear or use. Web API Server may renamed to Pakai framework in the future.

Note: All the words mentioned above can be formed from the combination of alphabets from the RESPONSE_ELEMENT constants that represent the properties of verbose mode.
You can find the following code on top of WebApiUtils.bas file. Have FUN!

' Web API Utility
' Version 4.30
Sub Process_Globals
    Public Const CONTENT_TYPE_HTML As String = "text/html"
    Public Const CONTENT_TYPE_JSON As String = "application/json"
    Public Const CONTENT_TYPE_XML As String = "application/xml"
    Public Const CONTENT_TYPE_PDF As String = "application/pdf"
    Public Const CONTENT_TYPE_PNG As String = "image/png"
    Public Const RESPONSE_ELEMENT_MESSAGE As String  = "m"
    Public Const RESPONSE_ELEMENT_CODE As String     = "a"
    Public Const RESPONSE_ELEMENT_STATUS As String   = "s"
    Public Const RESPONSE_ELEMENT_TYPE As String     = "t"
    Public Const RESPONSE_ELEMENT_ERROR As String    = "e"
    Public Const RESPONSE_ELEMENT_RESULT As String   = "r"
    Type HttpResponseContent (ResponseBody As String)
    Type HttpResponseMessage (ResponseMessage As String, ResponseCode As Int, ResponseStatus As String, ResponseType As String, ResponseError As Object, ResponseData As List, ResponseObject As Map, ResponseBody As Object, ContentType As String, XmlRoot As String, VerboseMode As Boolean, OrderedKeys As Boolean, ResponseKeys As List, KeysAlias As List)
End Sub

 

[aeric]

Version: 4.40

What's New

• RequestDataText sub added
• ReturnHttpResponse sub updated
• KeysAlias property renamed to ResponseKeysAlias
• Identation parameter spelling corrected to Indentation

 

[aeric]

Version: 4.50

What's New

• Updated HttpResponseMessage type
  • added XmlElement property
  • added PayloadType property
• Updated ReturnHttpResponse sub
  • fix XML support
  • many other bug fixes
• Updated ProcessOrderedJsonFromMap sub
• Updated ProcessOrderedXmlFromList sub
• Added ParseXML sub
• Added EscapeHtml sub
• Added ValidateContent sub
• Fix Main.conf.ServerUrl in Web Handler.txt Snippet

 

[aeric]

Version: 4.60

What's New

• Bugs fix in XML verbose mode
• Clean up unused code

 

[aeric]

Version: 4.70

Bugs fix for XML format

 

[aeric]

Version: 4.80

• Rebased on Pakai v4.00 for testing
• Reorganize folders in repo
• Small fix in ProcessOrderedJsonFromMap sub

 

[aeric]

Version: 5.00

• Add ReturnCookie2 sub (support path, samesite, secure)
• Rename variables

Example:

WebApiUtils.ReturnCookie2("refresh_token", "", "/auth/refresh", "", 0, True, False, Response)

can be use to clear the HttpOnly cookie (logout or delete JWT refresh token)
It is equivalent to:

Response.SetHeader("Set-Cookie", "refresh_token=; HttpOnly; Path=/auth/refresh; Max-Age=0")

 

[aeric]

Version: 5.10

• Update Snippets for Pakai Server v5.00+
• Convert blob value to base64encoded string in JSON and XML response
• Update ProcessOrderedJsonFromList sub
• Update ProcessOrderedJsonFromMap sub
• Update ProcessOrderedXmlFromList sub
• Update ProcessOrderedJsonFromMap sub

 

[aeric]

Version: 5.20

• Added SetApiMessage sub
  • Usage:
    Old:
    

    HRM.Initialize
    HRM.ContentType = Api.ContentType
    HRM.VerboseMode = Api.VerboseMode
    HRM.OrderedKeys = Api.OrderedKeys

    New:
    

    HRM.Initialize
    HRM = WebApiUtils.SetApiMessage(HRM, App.api)

• Renamed Content Type Constants
  • CONTENT_TYPE_HTML -> MIME_TYPE_HTML
  • CONTENT_TYPE_JSON -> MIME_TYPE_JSON
  • CONTENT_TYPE_XML -> MIME_TYPE_XML
  • CONTENT_TYPE_PDF -> MIME_TYPE_PDF
  • CONTENT_TYPE_PNG -> MIME_TYPE_PNG
• Removed Log("Blob Field")
• Updated Snippets
• Added ParseJSON sub
• Set XmlElement value to "item" as default in ReturnHttpResponse sub
• Added #Macro tags (for source project)
  • #Macro: Title, Release, ide://run?file=%WINDIR%\SysWOW64\explorer.exe&Args=%PROJECT%\..\release
  • #Macro: Title, Publish, ide://run?file=%JAVABIN%\jar.exe&WorkingDirectory=..\..\release&Args=-cMf&Args=%ADDITIONAL%\%PROJECT_NAME%.b4xlib&Args=*

Note: This version is not supported for Pakai Server v4. Use WebApiUtils v5.10 or below.
If you insist to use this library in Pakai Server v4,
1. Add the following line in Main:

Type ApiSettings (Name As String, Versioning As Boolean, PayloadType As String, ContentType As String, EnableHelp As Boolean, VerboseMode As Boolean, OrderedKeys As Boolean)

2. Replace the following:

WebApiUtils.CONTENT_TYPE_JSON -> WebApiUtils.MIME_TYPE_JSON
WebApiUtils.CONTENT_TYPE_XML -> WebApiUtils.MIME_TYPE_XML

 

[aeric]

Version: 5.30

What's New

1. Removed SetApiMessage sub (moved to EndsMeet library)
2. Updated Snippets\Api Handler.txt
   [CODE lang="b4x" highlight="2"]'HRM = WebApiUtils.SetApiMessage(HRM, App.api) 'deleted
   HRM = App.SetApiMessage(HRM, App.api) 'added[/CODE]
3. Added #Macro tag:
   

   #Macro: Title, Copy, ide://run?file=%WINDIR%\System32\cmd.exe&Args=/c&Args=copy&Args=%PROJECT%\WebApiUtils.bas&Args=%PROJECT%\..\release\WebApiUtils.bas

Note:
To use this version in Pakai Server v4, make changes to the following:

WebApiUtils.CONTENT_TYPE_JSON -> WebApiUtils.MIME_TYPE_JSON
WebApiUtils.CONTENT_TYPE_XML -> WebApiUtils.MIME_TYPE_XML

 

[aeric]

The Api Handler.txt code snippet is still generating code for WebApiUtils.CONTENT_TYPE_XML
This will be updated in next version.

 

[aeric]

Version: 5.40

What's New

1. Updated Code Snippet for Api Handler.txt
   • use new constant WebApiUtils.MIME_TYPE_XML
   • show invalid payload type in error message for Post and Put endpoints sub
   • updated code to use SetApiMessage sub from Main module
     [CODE lang="b4x" highlight="2"]HRM = App.SetApiMessage(HRM, App.api) ' deleted
     Main.SetApiMessage(HRM) ' added[/CODE]
2. Add new macros for
   • manifest writer
   • Objects folder

 

[aeric]

Version: 5.50

What's Updated

1. Fix wrong path for JavaScript in Web Handler.txt code snippet
2. Return single root element for XML response if no child elements
3. Move Code Snippets to source folder

 

[aeric]

Version: 5.55

What's Updated

1. Fixed small indentation formatting in ProcessOrderedJsonFromMap sub
2. Fixed small indentation formatting in ProcessOrderedJsonFromList sub
3. Small change in ReturnHttpResponse sub
4. Removed jServer from manifest.txt
5. Test project based on EndsMeet v1.80 and MiniORMUtils v4.20

 

[aeric]

Version: 5.60

What's New​

1. Added List2PrettyJson sub
2. Added Map2PrettyJson sub
3. Updated ProcessOrderedJsonFromList sub
4. Updated ProcessOrderedJsonFromMap sub
5. Updated ReturnHttpResponse sub
6. Updated to use 2 number of spaces for JSON indent
7. Updated Api Handler.txt (Code Snippets)