WebAPI

Lycia provides HTTP API for running 4GL programs and accessing its state. Using WebAPI, you can execute 4GL functions and interact with 4GL UI statements. Thus any 4GL application may be turned into a web service with little effort. In fact, any application deployed to Lycia Application Server using default settings is already published as a web service. No changes in your code or settings are required.

WebAPI can be used for:

After the application is deployed it can be immediately used as a web service.

The full WebAPI reference is available here (as a Swagger description).

To view the JSON file containing WebAPI description (the file is included in LyciaWeb client) use this link -  http://<your_app_domain.com>/LyciaWeb/esapi/swagger/v2/lycia-web.json.

Refer to WebAPI Example to see the API demo session, which uses cURL for the CMS demo application, running on Querix web server.

Due to limitations of the current Swagger specification not all details are listed there. The additional details are described in this document.

Overview

Web API uses Servlet standard session handling, and by default each application is assigned a session, where it stores its current state. You can run several applications simultaneously either by maintaining different cookie values, or using additional slot URL query parameter. It should be the same for the /run operation and other queries for that application. It can be a string, and it must uniquely identify running 4GL command.

All operations for running a 4GL application as a web service can be found using this link - http://<your_app_domain.com>/LyciaWeb/esapi/.

Any 4GL application deployed to Lycia Application Server can be run as web service using the /run operation. It takes a command line string and an instance name on a Lycia Application Server. Typical 4GL application is single threaded with explicit execution control state.

The application at any time can be in one of following states:

The application is ready for request when it is stopped in an interaction statement, such as  INPUT, PROMPT, MENU, DIALOG, or a function such as  fgl_getkey.

At this point  a client application can call a 4GL function, read and write values to form fields, signal a dialog action or simulate a key press. This is Idle state of application.

Some of these operations may cause exiting current interaction statement and entering another one. In this case it will return to Idle state.

Execution control can also enter the Question state while waiting for an input from client. For example, in a fgl_winprompt function. By default the system will answer empty value to the question and will go further up until next Idle or Stopped state. But if the noDefaultAnswer URL query parameter is provided, it will wait for answer to the question. The answer may be given with the /answer operation. It is the only POST operation that can be executed in this state (not considering /quit). After executing the operation, control will proceed as usual, until next state. Use the defaultAnswer parameter to edit the default answer.

These are common successful HTTP response statuses:

202 - ACCEPTED - execution control stopped at Idle or Question state, and no results yet provided.

200 - OK - execution control exited a function that was called earlier using the /call operation (this may be result of any POST operation, not only /call, since single function call may require several operations to be executed, for example, if it contains interaction statements).

The function can contain any 4GL including interaction statements (DIALOG, MENU, INPUT, PROMPT, DISPLAY ARRAY etc.), or function asking some question from front end, such as different message boxes, file dialog etc. If execution control enters some of these, it will stop and return 202 status code with status description JSON. To avoid this and get function result in single request, either write functions without such UI interaction code or provide default actions with the defaultAction parameter. It is 4GL action name which will be executed on each Idle state, until control exits the called function.

For example posting the following URL http://<your_app_domain.com>/LyciaWeb/esapi/call/calculate_income?defaultAction=accept will silently answer ACCEPT action to each interaction statement. Of course, the program should handle that action well. At least it should exit the statement so that execution control can reach function’s RETURN.

Function arguments can be passed using the 'args' parameter (should be a valid JSON array).

Refer here to see some basic examples of passing function arguments.

Do not use single quotes to wrap 'args' elements - JSON uses double quotes:

'args=["parameter #1","parameter #2","parameter #3"]'

If any 'args' elements contain double quotes, they must be escaped:

It is possible to call another function if execution stopped on interaction statement using the /call operation again. Thus several functions can be executing at the same time. For diagnostics they can be returned with the /current/stack operation.

Limitations:

No data virtualization for tables and screen arrays, all the data will be sent instantly, which can affect performance.

No support for RUN statements running 4GL application with UI (non UI commands should work without problems)

You can also call any 4GL function using the /call method. By default, for security reasons, only functions starting with the web_ prefix are published, but this can be changed.

For 4GL, more natural approach for implementing web services is to use interaction statements rather than function calls. It keeps the current execution state, thus the code is more readable. As input and output arguments form field values can be used. It also allows turning any 4GL application into a web service with zero efforts. After starting an application, execution control stops in a Question or Idle state. Current results may be returned any time using a /get operation. It returns current form field values. If it is a legacy application that frequently uses DISPLAY AT, results may be returned using the /current/screen operation.

For diagnostic purposes it is always possible to get a list of currently available action names with the /current/actions operation.

To run an action block, invoke the /action/{actionName} operation if the program is in the Idle state. It accepts JSON list of values in input parameter or there may be several _ arguments to set field values. After everything is set, the action specified in the actionName parameter will be executed, and it will wait utill next Question, Idle, or Stopped state.

The input parameter should be a valid JSON array with either simple types or JSON objects as elements. If it is a JSON object, it can have the following fields:

The API first sets focus to that field, then executes all the required handlers (such as BEFORE FIELD, or AFTER FIELD clauses) and puts the value into it.

If no field name and row is provided, the system will simply execute NEXT FIELD after previous value is set, moving focus to the next field, defined in 4GL program business logic.

The Swagger API reference defines parameters mostly sent in URL query, but they can be sent as form parameters as well. This is not included there to simplify reference.

The following information can be returned using the current API:

All these operations expect the GET method and do not change state of the currently running program.

The API can also handle binary data using fgl_upload, or fgl_download function calls in 4GL, or a form with binary fields bound. The form field value may be either returned using the /get operation, where it will be a base64 encoded string, or using the /blob operation, which will return raw data.

Form fields exchange is simpler but for large files the fgl_upload and fgl_download functions should be used. During execution of these functions, the application will go into Transfer state. Then, the corresponding operations should be executed (either /upload or /download).  For download, content will be a response body and for upload some multipart form field with content.

BLOB fields are downloaded using the /blob operation, and set on /set or /action operations, where their value is multipart form field this a name equal to a the one on form. Returning values using the /blob operation is similar to /set, but it returns raw content instead of JSON for BLOBs.

Related articles:

DIALOG

DISPLAY ... AT

DISPLAY ARRAY

fgl_download()

fgl_upload()

LyciaWebAPI Example

LyciaWeb API Reference

MENU

INPUT

PROMPT