Forms, Reports, Apps

Build and deploy rapidly. Use offline, online, on-premises.

  Blog

Blog
Tuesday, December 14, 2021PrintSubscribe
RESTful Apps With Hypermedia

Code On Time release 8.9.24.0 creates apps with the hypermedia-enabled REST API engine. The hypermedia controls elevate the engine to the Level 3 of Richardson Maturity Model

The new REST API engine significantly increases the value of your applications. It also offers new opportunities to leverage your Code On Time expertise in modern application development. The best part is that you accomplish both with just a few keystrokes!

Architecture of Code On Time Applications

Applications are composed of the server-side code and JavaScript-based frontend with the beautiful and responsive user interface. The frontend operates in any modern web browser and is capable of running in a completely disconnected mode on the native devices. The frontend makes HTTP calls into the server-side code to read and write data. 

Data Aquarium is the custom framework in the core of the server-side code. It provides a powerful foundation for application of any size. Model Builder, Access Control Rules, and Data Controller Virtualization give developers the tools to build out the application data presentation and processing. Custom business rules are written either in SQL or in the implementation language of the app (C# or Visual Basic). The framework provides the RPC-style endpoints for the frontend to request data and execute actions over HTTP. 

Server-Side Code as a RESTful App

Previously the frontend of a Code On Time application was the only client of the server-side code. The new REST API engine extends the applications to the infinite number of clients capable of making HTTP requests. The response data is returned in JSON, Yaml, or XML formats. Each response includes the hypermedia controls providing the clients with the options to navigate the resources and to change the state of data. 

Here is an example of the GET request to the REST API engine via the standard /v2 endpoint. The response is presented in the Postman, the popular API development tool. The “self” link in the “shippers” key suggests the means to obtain the corresponding data. The “first” link will lead to the first page of the data items. The “schema” link will assist in learning more about the data structure.


Follow the “self” link and you will get the response presented next. It includes the “collection” of items. Each item is provided with its own hypermedia controls. In this instance only the “self” link is available. The entire collection also has the hypermedia explaining how the data was obtained (the “self” link), how to transition to the first page of data (the “first” link), and how to create a new item with the POST method (the “create” link).


Follow the “create” link with the POST HTTP method. The engine will respond with the 403 HTTP error explaining that the field companyName is expected in the body of the request. The data schema is also included.


Let’s define the request body with the companyName and phone fields. Execute POST and the API will respond with 201 HTTP code indicating that the resource was created. The hypermedia controls give options to access the “collection” of items and to get the “first” page of data. We can also “edit”, “replace”, and “delete” the resource.


Let’s follow the “edit” link to change the phone number. We will need to execute the PATCH HTTP method for this link. The resource will change accordingly. 


Now destroy the resource by following the “delete” link with the DELETE method. The response with the HTTP code 200 will present you with the links to navigate to the “collection” or the “first” page of data.

Retry the same request and the HTTP response 404 will let you know that the resource does not exist.


Working With Hypermedia

Hypermedia as the Engine of Application State (HATEOAS) is the core feature of the REST API in the Code On Time applications. The hypermedia links are created dynamically to represent the state of a resource. The REST client needs only the basic understanding of the hypermedia to use the API. The clients programmed to use the hypermedia links are decoupled from the hard-coded URLs and can evolve independently from the server-side application.

Data View fields are contributing links to the details of the singleton master resources. Additional views in a data controller will contribute “collection-”, “first-”, and “create-” links. Custom actions will also supply their own links. Data Controller Virtualization is instrumental in providing the precise set of the resource hypermedia links that match the user identity of the request. Access Control Rules are limiting the data items presented in the responses. 

This is the example of the “supplier” singleton resource with the additional “self-”, “collection-” and “products” links.


The “products” links are embeddable in the resource when specified in the _embed parameter of the request URL. Here is the response to the request that uses the parameter and also excludes the hypermedia from the output with _links=false specified in the URL. 

The links above are excluded to make it easier to see the shape of data. If you are not convinced that programming the clients to use the hypermedia is a good idea, then specify the _links=false parameter in the URL of your requests. Hypermedia is still instrumental in understanding the API and resources.

Over-Fetching, Under-Fetching, and GraphQL

Facebook (Meta) has pioneered the GraphQL query language that has allowed it to unify the hundreds of the in-house APIs and eliminate the over-fetching and under-fetching of data. The term “over-fetching” generally refers to the REST APIs returning more data than the client needs. The response above pulls all fields of the supplier and products even though only some of the data may be needed for a particular client. Under-fetching describes the situation when the complex clients are required to make multiple calls to the API to pull the full set of required data.

The Data Aquarium framework in the foundation of Code On Time applications was designed to prevent over-fetching by the frontend. The REST API possesses the same gift. Developers can specify the fields parameter to represent the required fields in the GraphQL query style. The fields parameter parser will automatically configure the _embed parameter behind the scene. The hypermedia links are excluded in the response shown in the screenshot to improve the readability. You can see that the shape of data matches exactly the query in the fields.


A space or comma separated list of field names can be specified in the fields parameter when only the main resource data is needed.

Fragment products {unitPrice productName categoryId { picture description}} specified in the fields query is instructing the REST API Engine to follow the hypermedia link to the products and then to follow the link to the categoryId  for each product. This solves the problem of under-fetching by incorporating the entire data set in the response of a single request. 

Filtering and sorting on each level of the query graph is also supported.

The rigorous type checking of the request payload against the resource schemas is assisting developers in creating error-free requests.

Why Are We Building It?

The long-time fans follow the saga of our effort to rebuild the new community site. We have designed an ambitious content management system (CMS) called the Content Hub. This CMS can be integrated into any application created with Code On Time to infuse them with the built-in community forum, help desk, blog, and documentation platform. We are getting ready to roll it out soon! The new REST API is the foundation of the Content Hub backend.

The REST API engine also answers the persistent stream of requests from our customers to allow taking advantage of the data services of the applications they create. The new API is built on top of the HTTP architecture, making use of the resource-based URLs, HTTP methods, and content caching. The hypermedia makes it uniquely easy to learn and use. The REST API engine turns Code on Time into the middleware provider, while the app developers are becoming the expert backend gurus

Code On Time applications can serve as the backend for custom mobile and web apps, cloud process orchestration services, and much more. Start selling your data and business logic with state-of-the-art technology!

Our previous roadmaps have pointed to GraphQL as the core backend technology for Code On Time applications. The query demonstrated in the discussion of over-fetching is written with the GraphQL syntax. The follow-up releases will introduce the full GraphQL runtime for queries and mutations with the automatic generation of data and input types. The runtime will automatically resolve queries into the REST API engine requests. 

Assistant UI, the new text-based user interface for Code On Time applications is also in the works. It will allow the end users to text, email, and talk to your applications with the help of hypermedia!

RESTFul App Security

REST API engine must be explicitly enabled by setting the server.rest.enabled option to true. All data controllers will become accessible via the hypermedia links in the /v2 application endpoint unless restricted to a specific subset in the settings.

The authorization of the requests is mandatory. API keys can be listed explicitly in the settings or retrieved from the database. Each key must be associated with a particular user name. The keys will work great with the server-to-server communications. For example, a cloud function can invoke a custom method of a particular resource to cause the application to perform the background processing. API keys can be passed in the request header X-Api-Key or as api_key parameter in the URL. The latter will work best when submitting the data from the anonymous HTML forms.

If the “bearer token” authorization is enabled, then a dedicated “authorize” hypermedia link will become available in the /v2 endpoint. The link will allow the user to sign in and obtain an access token via the OAuth protocol. This authorization method works best for standalone mobile and web applications.

The client-side business rules of the Code On Time app frontend can invoke the $app.restful function to access the REST API via fetch. The access token of the logged in user is automatically obtained from Touch UI. The function will also renew the access token when needed. 

Developers may opt to create the frontend pages without Touch UI by placing the data-user-interface=”custom” attribute on the body element. The page will render as-is when the attribute is detected. Custom JavaScript and CSS libraries can be linked to such pages as needed to create a unique presentation in the frontend. Link the file ~/js/sys/restful-2.0.js to the page to make it possible to invoke $app.restful and access the REST API of the application with the current user identity. The pages with the custom user interface will co-exist with the Touch UI pages of the application and share the common login screens.
Labels: REST
Monday, October 4, 2021PrintSubscribe
2-Factor Authentication, "Actions" Lookup Style, Tap to Copy, Login Responses

 Code On Time release 8.9.23.0 is introducing the enterprise-grade security feature that helps secure the user accounts. 2-Factor Authentication is opt-in by default. It can also be applied to all users accounts in the existing and new apps automatically. Another highlight of the release is the option to inject the actions directly into the flow of the data fields in the forms. Multiple enhancements and bug fixes are also included in this release.

2-Factor Authentication

The new feature will require the verification code to be entered after the valid combination of username and password was provided by the user during login. The verification code can be delivered by an authenticator app installed on the personal mobile device. Other options include an email, text message, or voice call. Developers may even choose to hide the password field in the login form if the 2-Factor Authentication setup mode is automatic. 


The new multi-factor authentication enhances the protection of the user accounts. This feature was sponsored by Peter Marchal of Wonderland Office, Belgium. 

“Actions” Lookup Style

The new lookup style “Actions” makes it easy to inject the actions in the flow of data fields of a form. Action buttons placed right next to the relevant data fields gain better context and improve the user experience. The visibility of the individual action is controlled by “When…” properties associated with the action. The visibility of the entire cluster of action buttons is controlled through the Visible When property of the data field that has its lookup style set to Actions and the Name set to match the Id of the corresponding action group. 


Tap to Copy

The new tag text-action-copy will cause the “Copy” button displayed next to the data field value. Tapping or clicking on the button will cause the field value to be copied into the clipboard. See this feature in action in the screenshot above. The text is copied to the clipboard and also displayed in the notification at the bottom of the screen when the button is clicked.

Custom Login Responses

If the user login has failed, then the generic message “Your user name and password are not valid” is displayed by the apps. If the login was successful then the user is silently signed in. Sometimes a custom message or system response is desired. 

Consider the following examples:
  • The user account is locked and it is preferable to let the user know what actions must be performed to recover the account. 
  • Developers may need to inform the user about the number of remaining login attempts before the account is locked.
  • Multi-factor authentication must force the user to enter the verification code if the login was successful. 
Learn about Custom Login Responses in Code On Time apps.

Releases Notes

The the following features, enhancements and bug fixes are included in the release:
  • (Classic UI) Removed the link that allowed downloading the import template. 
  • (Touch UI) Fixed the incorrect reference to the API function in the import processor. This was causing the error with the long running imports when the status was updated.
  • (App Gen) Replaced the legacy community reference with my.codeontime.com.
  • (Virtual Keyboard)  The keyboard is minimized when the window loses focus and re-activates when the focus is restored.
  • (Framework) Moved methods and classes from ApplicationServices.cs(vb) to ApplicationServices.Auth.cs(vb).
  • (Class Library Apps) Files touch-edit.js and touch-input.js are copied to the ~/app/js/daf folder of the apps with the class library to enable debugging in Unlimited Edition apps.
  • (Framework) Method $app.prettyText formats international names as "pretty" strings.
  • (Universal Input) List box/ Check Box List / Radio Button List with 1 item has a compact presentation.
  • (Input) Qr code does not show the tooltip if the field is tagged as input-qrcode-tooltip-hidden.
  • (TouchUI) Check Box List item state transition is twice faster.
  • (Touch UI) Survey actions support the position=before|after option. If the option is not specified then actions are inserted just before the Cancel button. Actions with "before" position are placed before the "Submit" button. Actions with the position "after" are placed after the Cancel button.
  • (Framework) Method dataView.data('survey') returns the context data or a "survey" dataview. Used in the Property Grid and 2FA forms.
  • (Touch UI) The first row in the form category without the header will have a slightly large top padding.
  • (Touch UI) Freezing of the column in the grid with aggregates will not cause the exception.
  • (Touch UI) Keys F2 and Arrow Down will focus the first row in the focused DataView field in the form.
  • (Framework) Transaction processor correctly parses the temporary UIDs and resolves negative primary keys into "old" values encoded as UID if the corresponding new value is also the UID.
  • (Framework) Method Commit resolves the temporary primary key presented as negative integer or as uid in the format 000000000000-0000-0000-0000-00000001 with the key value recorded in the last segment.
  • (ODP) Client-side temp GUID primary keys are generated in the following format: 00000000-0000-0000-0000-00000000001. Only the last 12 digits are used to encode the temporary primary key, while the leading characters are set to 0.  The server-side framework resolves such GUIDs with the physical database values.
  • (Model Builder) Data View fields created in the model builder will have the filter fields correctly matched to the corresponding field names. Previously the original column name was used instead. If the output field name based on the column was not spelled in the same way then there will be incorrect filtering at runtime.
  • (App Gen) The codedom compiler now supports << (left shift) and >> (right shift) operators in C# and VB.
  • (Touch UI) Tag merge-with-prevous will cause the row to render without a separator line at the top to allow creating a contiguous group of fields in the form layout.
  • (Surveys) Setting the "text" of the question to "false" will cause the label to be blank.
  • (Touch UI) Setting the Label or Header Text of a field to $blank will result in a blank label of the field.
  • (Touch UI) Removed legacy references to the class ui-group-theme-a and ui-panel-page-container-a.
  • (Framework) If the style of field items is set to Actions then the field is marked as "virtual".
  • (Universal Input) Tag input-qrcode-size-192x192 will also trigger a custom input creation. The only input implemented now is "qrcode".
  • (Surveys) Survey definitions support causesCalculate on the actions and htmlEncode on the questions.
  • (Framework) Server-side method PopulateStaticItems will correctly assign Controller and View of the request to the internal ViewPage instance to ensure correct population of Many-to-many field with the static values (Check Box List, Drop Down List basket, List Box basket) when the Context Fields property of the many-to-many field property is set to X=Y. (X is the name of the filter and Y is the name of the field that will provide the value for X).
  • (Virtual Keyboard) Event beforefocus.keypboard.app is triggered on the data input prior to the keyboard gaining the focus. The handler can assign the callback method to the e.context.change property through the "e" argument of the event handler to be notified about changes to the text in the keyboard input.
  • (Virtual Keyboard) The virtual keyboard API is loaded when [data-input] elements are detected on the page to reduce the initial JS payload of the page.
  • (Universal Input) New virtual keyboard "pin" is now included with the framework. Tag a field as kbd-pin to have the keyboard displayed on touch devices.
  • (Universal Input) Virtual keyboard will not shift focus to the next input on tab or enter key if the user interface is in transition to another page at the moment of closure.
  • Thank you Roberto Ivon for contributing the "es" localization files.



Labels: Release Notes
Monday, October 4, 2021PrintSubscribe
Custom User Login Responses

 The introduction of the 2-Factor Authentication in the application framework has required changes to the login process. The framework challenges the users to enter a verification code to confirm their identity. Method CreateUserLoginResponse(username, success)  in the ApplicationServices partial class creates the JSON object with the instructions for the client-side code when the verification is needed.

Developers can take advantage of the new method to provide custom responses informing the user about the remaining login attempts, locked account, and other special cases. Otherwise the framework displays a generic message “Your user name and password are not valid.”

The sample code below will let the user name if the account is locked or display a notification at the bottom of the screen. The code executes only if there is no login response created by the base implementation to avoid conflicts with the multi-factor authentication.


Invalid username or password will yield a notification message when the JSON object with the notify property is returned.


A more prominent response is provided if the responses includes the alert property.


If the event property is returned in the response, then the framework will raise the client-side event on the document object with the response passed as the args property of the event. 2FA implementation uses this method to pass extended information to the client library.