fglrestful

The fglrestful tool produces REST web services stub files for client programs using an OpenAPI specification.

Syntax

fglrestful [ options ] service

options are described in fglrestful options and in fglrestful network options.
service is the OpenAPI service definition file or URL.

Options

Table 1. fglrestful Options
Options	Description
`-V` or `--version`	Displays version information.
`-h` or `--help`	Displays options for the tool.
`-l` or `--list` `{` `path \| resource` `}`	List all the paths or resources of a service. See List path or resource.
`-o` or `--output filename`	Specify a name for the output stub file. See Generate the stub file.
`-n` or `--name resource`	In a service providing access to one or more resources, specify the creation of a stub file for a given resource. See Generate stub file for resource.
`-p` or `--prefix prefix`	Set a prefix for constants and variables.
`--typePrefix prefix`	Set a prefix for types. Where `prefix` allows you to add a prefix in front of the name of types in a JSON schema. See Set types with prefix value.
`-b` or `--binary` `{` `byte \| file` `}`	Specify that binary types are generated as either `BYTE` or `FILE` types in the stub.
`-f` or `--format` `{` `xml \| json` `}`	Specify the preferred REST format (xml or json). You must use lowercase xml or json in the command.
`-a` or `--oauth` `{` `yes \| no` `}`	Specify if OAuth specification should be generated or not: With option "yes", OAuth support code is generated even if the OpenAPI documentation does not specify it. With option "no", OAuth support code is not generated even if the OpenAPI documentation requires it. If you do not use the `--oauth` argument, fglrestful generates the OAuth support code by default if it is specified in the OpenAPI documentation.
`--legacyJSONApi`	Generate stub file with legacy JSON API (`util.JSON`) when used with the --output option. See Usage.
`--ignore-restrictions`	Ignore JSON schema restrictions for data types: `VARCHAR(N)`, `DECIMAL(P,S)`, and `DATETIME` types.
`--datetime-fraction { 1 \| 2 \| 3 \| 4 \|5 }`	Specify `DATETIME` fraction qualifier. The default is `NULL`, meaning `YEAR TO SECOND`. If value is between 1 and 5, fglrestful generates `YEAR TO FRACTION(N)` where `N` is the value provided.
`-t` or `--token token`	Specify the access token value if the service is protected by an access token.
`-k` or `--tokenfile filename`	Specify the access token file if the service is protected by an access token.
`--comment`	Add comments to the generated stub file. See Output comments.
`-W` or `--Warnings` `{` `yes \| no` `}`	Specify if warnings should be output or not. By default the option value is `yes`, meaning the warnings are reported. See Output warnings.

Table 2. Network options (when specifying a URL)
Options	Description
`--proxy location`	Connect via proxy where `location` is `host[:port]` or `ip[:port]`.
`--pLogin login`	Proxy authentication login.
`--pPass pass`	Proxy authentication password.
`--hLogin login`	HTTP authentication login.
`--hPass pass`	HTTP authentication password.

Usage

You use the fglrestful tool to generate the GWS client stub from an OpenAPI documentation file (JSON format). The fglrestful command line tool supports OpenApi version 3. For usage options, run the command fglrestful without any other parameters or with the help ( -h ) option.

For example, to access a web service, you must get the REST information from the service provider. If the server supports the OpenAPI specification, the fglrestful command can generate the description of the service for access by a GWS client application.

If your REST service is written with Genero REST high-level API, a documentation file is provided by default when you launch the service with the query string ?openapi.json. If the GWS Server was started on your local machine, for example, the OpenAPI information would be at:

http://localhost:8090/MyService?openapi.json

If your REST Web service uses versioning and contains different versions of operations, you request the OpenAPI information for a given version with a query string &version=version-name. For examples, see Generate stub file for a version

In the next sections there are examples of common commands used by REST web service developers.

Generate the stub file

You can generate the stub file from the OpenAPI documentation in a command with the --output or -o option. For example, you can use the command in the following ways:

Using the URL of the running service:

fglrestful -o myStub http://localhost:8090/MyService?openapi.json

Or using an OpenAPI documentation file. If you access the OpenAPI information on the browser, you can copy the description to a file and save the file with an openapi extension, for example, myservice.openapi. Then run the command to generate the stub file from this:
```
fglrestful -o myStub myservice.openapi
```
Tip:
In Genero Studio, you can place the openapi file in your project and the stub file is generated from it when you compile the file. For more information, see the Genero Studio User Guide.

The generated client stub file, myStub in the example, is a Genero BDL file (.4gl).

By default, fglrestful uses the JSON streaming API to generate the stub file code. It is possible to use the old JSON API (util.JSON) instead by specifying the --legacyJSONApi option:

fglrestful -o myStub --legacyJSONApi myservice.openapi

Set types with prefix value

Using the --typePrefix option, allows you to add a prefix in front of named types in a JSON schema.

For example, you can use this option when generating the stub file to ensure types do not have the same names as Genero reserved words or libraries, such as "base", "util", and so on, in BDL variables. In the example, using the URL of the running service, the prefix "foo" is added to all named types:

fglrestful -o myStub --typePrefix foo http://localhost:8090/MyService?openapi.json

In the generated stub file, the "Base" type is renamed, and whereever it is referenced, to "foo_Base":

# components/schemas/foo_Base
PUBLIC TYPE foo_Base RECORD
    id INTEGER,
    path STRING
END RECORD
#...
PUBLIC TYPE useBase RECORD
  id INTEGER,
  country foo_Base,
  postal_code VARCHAR
END RECORD

List path or resource

The

--list {
path | resource }

option provides you with the option to list all the paths or resources of a service. For example, you can use a command to list the resources of the web service in the standard output:

using the URL of the running service:

fglrestful -l resource http://localhost:8090/MyService?openapi.json

or using a specification file:

fglrestful -l resource myservice.openapi

Generate stub file for resource

Your REST web service may provide services for one or more resources. You can specify the creation of a stub file for a given resource with the -n option in the command. For example, these commands generate a separate stub file for the "users" resource:

using the URL of the running service:

fglrestful -n users -o myUsersStub http://localhost:8090/MyService?openapi.json

or using a specification file:

fglrestful -n users -o myUsersStub myservice.openapi

Generate stub file for a version

Your REST web service may use versioning containing different versions of operations. You can specify the creation of a stub file for a given version with a query string &version=version-name in the command. For example, these commands generate a separate stub file for the "v2" version:

using the URL of the running service (the URL must be enclosed in quotes):

fglrestful -o myVersion2Stub "http://localhost:8090/MyService?openapi.json&version=v2"

or using an OpenAPI documentation file that contains the version 2 operations only:
```
fglrestful -o myV2Stub myserviceV2.openapi
```

If the requested version does not exist, the 404 error will be returned.

Output comments

When you specify the option --comment in the command, descriptions set on the WSDescription and WSTypeDescription attributes are generated in the stub file. For example, these commands generate a stub file with comments:

using the URL of the running service:

fglrestful -o myStub --comment http://localhost:8090/MyService?openapi.json

or using a specification file:

fglrestful -o myStub --comment  myservice.openapi

The descriptive text appears in the generated stub file in curly braces, for example:

PUBLIC TYPE user RECORD {This is a user}

 p_resourceId INTEGER {this is the customer id}

The WSDescription set on the ATTRIBUTES() clause of the function is not affected. It is always generated; even if the --comment option is not specified.

Output warnings

If you need to see warning messages when generating the client stub, you can specify the -W option in the command. In the example commands, warnings are written to the standard output:

using the URL of the running service:

fglrestful -W yes -o myStub http://localhost:8090/MyService?openapi.json

or using a specification file:

fglrestful -W yes -o myStub myservice.openapi

The warning message gives the path in the openapi.json file where you locate the issue, and gives the reason.

Warning in /paths/Property/GetAllProperties/{applicationID}/{includeWillBeSold}/{update}/get/responses
Reason : Unsupported media='text/plain' on type='WebAPI_CreditAnalysis_Models_PropertyContainer'

Errors are reported by default. The error message gives same kind of path, but with Error in instead of Warning in.