Web Services changes
There are changes in support of web services in Genero 6.00.
REST functions must include a RETURNS() clause
Starting from FGLGWS 6.00.01, all REST functions must declare a RETURNS()
clause, even when the function does not return a value. This enforces consistent function signatures
and prevents ambiguous web service definitions.
Action needed:
- You must add a
RETURNS()clause to every REST function declaration. -
Update your existing REST functions to include a
RETURNS()declaration — either an explicit return type or an emptyRETURNS().
Omitting the RETURNS clause will raise error -9158
For example:
FUNCTION notifyUser(userId INTEGER)
ATTRIBUTE(WSPost)
# ...
END FUNCTIONBefore (returns
data):FUNCTION notifyUser(userId INTEGER)
ATTRIBUTE(WSPost)
# ...
RETURN "data"
END FUNCTIONRETURNS() must be
added):FUNCTION notifyUser(userId INTEGER)
ATTRIBUTE(WSPost)
# The web service function 'notifyUser' requires a RETURNS() clause.
# See error number -9158.
END FUNCTIONNow (returns data — explicit
RETURNS(return-type) must be
added):FUNCTION notifyUser(userId INTEGER)
ATTRIBUTE(WSPost)
# The web service function 'notifyUser' requires a RETURNS() clause.
# See error number -9158.
RETURN "data"
END FUNCTIONFor more information about using RETURN clauses in RESTful
functions, go to Return value attributesJSONEnum: separator changed from pipe to comma
Starting from FGLGWS 6.00.01, the JSONEnum attribute uses commas instead
of pipes to separate values in its list (for example,
"pending","approved","rejected"). Update declarations that use the old pipe format
to the new comma-separated format to avoid validation errors.
An invalid separator will raise error -9159
Example:
Before:
TYPE ok_string STRING
ATTRIBUTE(JSONEnum = `"pending"|"approved"|"rejected"`)
Now:
TYPE ok_string STRING
ATTRIBUTE(JSONEnum = `"pending","approved","rejected"`)
For more details, go to JSONEnum
Implicit type conversions in json.Serializer have been removed
Starting from FGLGWS 6.00.00, implicit type conversions in json.Serializer have been removed.
For example, previously you could deserialize a JSON string like "true" to a FGL
BOOLEAN (1), or "123" to a FGL
INTEGER (123).
Now, these assignments will result in errors unless explicitly authorized.
-
If your application relied on automatic type conversions during JSON serialization/deserialization with
json.Serializer, you must now handle these conversions explicitly or useutil.jsonif you require the old behavior. -
The
allowImplicitConversionsetting does not restore the previous implicit conversion behavior injson.Serializer.
Ensure that JSON payloads sent to your 4GL applications use the correct types, as mismatches will now result in errors rather than silent conversions.
For more details, go to Implicit and explicit JSON conversion for primitive types.
Change in allowImplicitConversion behavior
The handling of implicit conversions for BDL types has also changed. Previously, primitive types
were always allowed to convert implicitly, regardless of the setting. Now, implicit conversions for all
BDL types, including primitive types, are controlled by this option. If it is not set to
allowImplicitConversion1, implicit conversions are no longer permitted.
For more details about the json.Serializer
allowImplicitConversion option, go to allowImplicitConversion.
Restored HandleRequest() behavior for root-level query-only requests
The behavior of com.WebServiceEngine.HandleRequest() for root‑level, query‑only requests has been restored to match versions prior to 5.01.02 and 4.01.09. The sequence of changes is as follows:
| Version | Behavior |
|---|---|
| Before v5.01.02 and v4.01.09 | Query‑only requests to the REST service root path (for example,
/service?abc) were treated as non‑REST and fell back to low‑level handling (status
1). |
| v5.01.02 and v4.01.09 | These requests were interpreted as REST requests. Because no operation exists on the service
root path, the engine returned error −35 instead of using the low‑level
handler. |
| Now with v4.01.11, v5.01.06, and v6.00.02 | The previous fallback behavior has been restored. Root‑level query‑only requests again fall back to low‑level handling when no REST operation matches. |
This restoration ensures compatibility with existing applications that depend on low‑level handling of root‑level query‑only requests.
For more details and examples, go to com.WebServiceEngine.HandleRequest
Response body allowed on a PATCH operation
Starting from FGLGWS 6.00.03, a WSPatch operation can declare a response
body.
Where previously the compiler rejected a PATCH function whose return value was not a header, raising error -9129, that function now compiles.
Existing code needs no change. A PATCH function that returns its values as headers with the WSHeader attribute continues to work.
For details, go to HTTP verbs and attributes.
Enhanced control of HTTP error messages in preprocessing and postprocessing
Starting from FGLGWS 6.00.02, you can set the "HTTPProcessingErrorMsg" context
key in WSPreProcessing and WSPostProcessing callbacks to supply a custom
HTTP reason phrase for non‑zero status returns. This update extends the existing WSContext capabilities by giving you more control
over the error message sent to the client. For more details, go to Using preprocessing and postprocessing callbacks
Global tags generation
Starting in version 6.00.02, all tag names defined with the WSTags attribute are now collected and generated once in the OpenAPI document’s global tags section.
The tags keyword is case-sensitive. For more details about tag behavior, go to WSTags.
fglrestful now recognizes +json media types (RFC 6839)
Starting from FGLGWS 5.01.06 and 6.00.03, the fglrestful tool recognizes
all media types derived from JSON via the +json structured syntax suffix defined
by RFC 6839 (external link). Previously, only application/json and text/json
were recognized; other +json media types in OpenAPI content sections were handled
as binary, causing the generated client stub code to expect binary data rather than JSON.
No action is required. If your OpenAPI specification uses +json media types
such as application/problem+json or application/vnd.api+json,
fglrestful now generates the corresponding client stub code from the associated
OpenAPI schema, with JSON serialization of the request body and JSON parsing of the
response.
For more details about supported media types, go to fglrestful.
CHAR(n) fields now include maxLength in the OpenAPI schema
Starting from FGLGWS 5.01.07 and 6.00.03, the OpenAPI specification generated for a REST service
includes maxLength: n for a CHAR(n) field, aligning it with
VARCHAR(n); a client stub regenerated with fglrestful maps the
field to VARCHAR(n) instead of STRING. Where previously
CHAR(n) produced only type: string, you must now review stub files
generated for services that expose CHAR(n) fields, or pass
--ignore-restrictions to retain the STRING mapping. For details, go to
OpenAPI types mapping: BDL.
fglrestful now detects text/event-stream (SSE) responses
Starting from FGLGWS 5.01.07 and 6.00.03, fglrestful detects the
text/event-stream (Server-Sent Events, SSE) response content type but does not
generate response-handling code for it, because the Genero HTTP client does not provide an API to
consume SSE streams. Previously, fglrestful could generate an incorrect response
handler for SSE responses.
No action is required if your OpenAPI specification uses text/event-stream
alongside another response content type. If text/event-stream is the only declared
response content type, fglrestful skips the operation, issues a warning, and
writes the operation as a comment in the generated .4gl file (run fglrestful
with -W yes to list skipped operations). You must implement SSE handling manually
if you need this operation. For more about SSE, go to Server-Sent Events on MDN.
For more details about supported media types, go to fglrestful.
Improved communication protocol between GAS and GWS
The communication protocol between the Genero Application Server (GAS)
and the Genero Web Service (GWS) processes has been updated to improve reliability, specifically to
ensure that no connections are lost when the GWS process needs extra time to stop or restart. Prior
to this update, if the GWS process needed time to stop, connections could be lost or requests could
be sent before the service was ready. The protocol was enhanced so that gwsproxy
now ensures fglrun is ready to receive the next request before proceeding.
To ensure you are using this improved communication protocol between the GAS and your GWS applications, ensure you are using the following version pairs (or greater):
-
FGLGWS 6.00.02 and GAS 6.00.03
fglrestful mapping of OpenAPI duration properties
Starting from GWS 6.00.03, fglrestful generates
INTERVAL DAY(9) TO FRACTION(5) instead of STRING for OpenAPI
properties declared with format: duration. Use
--interval STRING to restore the previous STRING mapping. For
details, go to Date-time and duration options.
Changes to the OpenAPI format mapping for DATETIME and INTERVAL
Starting from FGLGWS 6.00.03, changes for DATETIME and INTERVAL types affect how the GWS
writes the OpenAPI document, and how fglrestful interprets that document when
you regenerate a client stub.
The datetimeSerializationMode and intervalSerializationMode options of
json.Serializer allow the RFC 3339 and ISO 8601 formats, where previously the GWS
wrote only the native BDL form:
datetimeSerializationMode: you can set it to"FGL"(default) for the native BDL form,"RFC3339/UTC"for RFC 3339 normalized to UTC, or"RFC3339/TZO"for RFC 3339 with the local time zone offset.intervalSerializationMode: you can set it to"FGL"(default) for the native BDL form, or"ISO8601"for the ISO 8601 duration format.
By default, the GWS uses the "FGL" mode, unless you set the options in your
REST service.
For an example of each format, go to Table 1.
Previously, the GWS generated every DATETIME with
format: date-time, and INTERVAL as a plain string. The following
table shows the format keyword that it generates now:
| BDL type | OpenAPI property |
|---|---|
DATETIME YEAR TO DAY |
format: date. Setting datetimeSerializationMode does not
change it. |
DATETIME YEAR TO MINUTE, YEAR TO SECOND, or
YEAR TO FRACTION(n) |
|
Other DATETIME qualifiers, such as YEAR TO MONTH,
YEAR TO HOUR, or HOUR TO MINUTE |
No format. Setting datetimeSerializationMode does not
change it. |
INTERVAL |
|
fglrestful then declares the stub type from the OpenAPI property:
| OpenAPI property | Stub type (default) |
|---|---|
type: string, format: date |
DATE |
type: string, format: date-time |
DATETIME YEAR TO SECOND |
type: string, format: duration |
INTERVAL DAY(9) TO FRACTION(5) |
type: string, no format |
STRING |
PUBLIC TYPE tOrder RECORD
shipDate DATETIME YEAR TO DAY, # format: date
updated DATETIME YEAR TO SECOND, # no format in the default mode
period DATETIME YEAR TO MONTH, # no format, whatever the mode
leadTime INTERVAL DAY TO SECOND # no format in the default mode
END RECORDPUBLIC TYPE tOrder RECORD
shipDate DATETIME YEAR TO SECOND,
updated DATETIME YEAR TO SECOND,
period DATETIME YEAR TO SECOND,
leadTime STRING
END RECORDNow (stub generated from an FGLGWS 6.00.03 service in the default
mode):PUBLIC TYPE tOrder RECORD
shipDate DATE,
updated STRING,
period STRING,
leadTime STRING
END RECORDReview the code that uses these fields. What you can do depends on the qualifier:
- For
DATETIME YEAR TO MINUTE,YEAR TO SECOND, orYEAR TO FRACTION(n)fields, you can keepDATETIME YEAR TO SECONDby settingdatetimeSerializationModeto"RFC3339/UTC"or"RFC3339/TZO"in the REST service before you fetch its OpenAPI document. This also changes theDATETIMEvalues in the service's JSON responses, for every client, for example"2024-11-05T08:15:58Z"instead of"2024-11-05 09:15:58". Before you change the mode, check that the other clients of the service accept the RFC 3339 form. - For
YEAR TO DAYand the other qualifiers, setting the serialization mode does not bring the previous type (DATETIME YEAR TO SECOND) back.
For details, go to DATE, DATETIME, and INTERVAL conversions.
DSA signature key
Starting from FGLGWS 6.00.03, the xml.CryptoKey class supports the
dsa-sha256 signature key for DSA digital signatures. SHA-1 is deprecated;
where previously you used http://www.w3.org/2000/09/xmldsig#dsa-sha1, you
must now update your code to use
http://www.w3.org/2009/xmldsig11#dsa-sha256. For details, go to Supported kind of keys.
REST API catalog endpoint
Starting from FGLGWS 6.00.03, the GWS engine intercepts
GET /.well-known/api-catalog before any user request handler and returns an
RFC 9727 API catalog of the application's REST services. An application that previously handled
this path itself gets the engine's response instead. For details, go to
REST API catalog.
fglrestful mapping of allOf compositions
Starting from FGLGWS 6.00.03, fglrestful generates code that compiles for
allOf compositions of primitive JSON types, and for object subschemas that define
the same property.
In earlier releases, a composition of primitive types generated code that did not compile, or stopped generation with an error, and a property defined in several subschemas generated code that did not compile, returning error -4319 (symbol defined twice) or error -9154 (duplicate allOf property).
After upgrading, review any generated types that come from specifications using these patterns,
as the generated output may change. Be aware that with --no-merge-allof, several
$ref subschemas that define the same property still return error -9154, which you
correct in the generated code by hand.
For details, go to allOf schema composition.
JSON serializer boolean option values
Starting from FGLGWS 6.00.03, the allowNullAsDefault,
serializeNullAsDefault, and allowImplicitConversion options of
json.Serializer.setOption() accept only the string "1" to enable the
option (or the INTEGER 1, or the BOOLEAN
TRUE), and the string "0" to disable it (or the INTEGER
0, or the BOOLEAN FALSE).
In earlier releases, the value was converted to an INTEGER. Any non-zero number,
such as 2 or -1, enabled the option, and a value that is not a
number, such as the string "true", an empty string, or NULL,
disabled it. A number with spaces around it, such as the string " 1", was converted
to that number. After upgrading, each of these values raises error -15824.
After upgrading, review any setOption() calls that set these options from a
variable, an expression, or a value read from configuration.
For details, go to json.Serializer.setOption.
External DTD of XML request and response bodies
Starting from FGLGWS 6.00.03, the web services engine no longer fetches the external document type definition (DTD), or any other external entity, of an XML request or response body that it parses.
This change improves security by preventing XML external entity
processing, which could cause the server to fetch from a network address or a file on the server.
This applies to SOAP and REST services and clients, and to the com methods that read
an XML body, such as com.HttpServiceRequest.readXmlRequest and com.HttpServiceRequest.beginXmlRequest.
The engine now ignores the external DTD and the external parameter entities of a body, without
raising an error. The attribute default values declared there no longer apply. If the body
references an entity that only the external DTD declares, the engine either replaces the reference
with an empty value or fails to parse the body. On macOS and iOS with a libxml2 version older than 2.13, the attribute default values
declared inside the body's <!DOCTYPE> no longer apply either.
After upgrading, review any service or client whose XML bodies rely on an external DTD.
For details, go to DomDocument Features and StaxReader Features.
load-external-dtd feature of the XML classes
Starting from FGLGWS 6.00.03, the xml.DomDocument and
xml.StaxReader classes have a load-external-dtd feature, which
defines whether a parse fetches the external DTD of a document.
The feature is TRUE by default, so existing
programs fetch external DTDs as before.
An xml.DomDocument that sets enable-html-compliancy to TRUE, then
back to FALSE before loading XML, now follows the load-external-dtd feature like any
other document. Previously, it fetched the external DTD without applying its attribute default
values.
After upgrading, review any program that parses XML from a source that you do not control, such as a
response from a third party or a file that a user uploads, and set load-external-dtd
to FALSE for those documents.
For details, go to DomDocument Features and StaxReader Features.
SAML identity provider certificate and assertion checks
Starting from FGLGWS 6.00.03, the SAML service provider delivered in $FGLDIR/web_utilities/services/saml verifies the signatures of an identity provider (IdP) against the signing certificate imported from that IdP's metadata. It also refuses assertions that do not carry the conditions the SAML Web Browser SSO profile requires. After upgrading, the service provider can refuse the logins of an IdP until you re-import its metadata.
For details, refer to SAML identity provider certificate and assertion checks in the Single Sign-On User Guide.
Changes to how GWS handles an invalid HTTP request
Starting from FGLGWS 6.00.03, when a Web Services server application receives a request that is not valid HTTP, the server responds to the client with an HTTP error status, and the application keeps running.
Where previously such a request put the server into an invalid
state, and every later call failed with the same error, the application now goes on processing
requests.
For such a request, com.WebServiceEngine.ProcessServices() and
com.WebServiceEngine.HandleRequest() return status -5
instead of -8.
com.WebServiceEngine.GetHTTPServiceRequest() still raises error -15565.
After upgrading, review any request loop that tests for -8, and handle -5 there.
For details, go to com.WebServiceEngine.ProcessServices.
Changes in earlier versions
Make sure to check the upgrade notes of earlier versions, to not miss changes introduced in maintenance releases. For more details, go to Web services changes in BDL 5.01.
- Stricter handling for nulls in serialization of primitive types, objects, and arrays introduced in FGLGWS 5.01.00.
- json.Serializer.getLastErrorDescription method to provide a
more complete message than
sqlca.sqlerrmfor a generated serialization error message introduced in FGLGWS 5.01.01. - Register web services and resources from a package feature introduced in FGLGWS 5.01.02.
- New json.Serializer option for handling implicit conversion,
allowImplicitConversion, introduced in FGLGWS 5.01.03. - Support for Online Certificate Status Protocol (OCSP) was discontinued for FGLGWS versions 3.21.02, 4.01.07, and 5.01.03.
- fglrestful now recognizes
+jsonmedia types (RFC 6839) introduced in FGLGWS 5.01.06 and 6.00.03. - maxLength generated for CHAR fields in OpenAPI introduced in FGLGWS 5.01.07 and 6.00.03.
- fglrestful now detects
text/event-stream(SSE) responses introduced in FGLGWS 5.01.07 and 6.00.03.