Web Services changes
There are changes in support of web services in Genero 5.01.
The handling of NULL values for primitive types during serialization has changed
Starting from FGLGWS 5.01.00, there are changes to how nulls are handled in primitive types.
Previously, when null values were passed, the GWS sent null. Now
error-15807 will be raised if
a null value is sent. Where previously you did not have an option to allow null
values, you must now review your code to explicitly allow nulls. The following is a summary of the
behavioral changes for handling nulls in primitive types, objects, and arrays:
- Primitive type: If the value is
NULL:- Before: It was serialized to
NULL. - Now: If the
json_null="null"attribute is not set or the serializeNullAsDefault option is not set to 1, a serialization error is generated.
- Before: It was serialized to
- Object: If a primitive type field is
NULL, it is omitted unless there is aJSONRequiredattribute set:- Before: It was serialized to
NULL. - Now: If the json_null="null" attribute is not set or the serializeNullAsDefault option is not set to 1, a serialization error is generated.
- Before: It was serialized to
- Array: If an index is
NULL:- Before: It was serialized to
NULL. - Now: If the
json_null="null"attribute is not set or the serializeNullAsDefault option is not set to 1, a serialization error is generated.
- Before: It was serialized to
For more information about serialization, go to json.Serializer options.
Using the json_null="null" attribute with
JSONRequired
Starting from FGLGWS 5.01.00, json.Serializer class
introduces changes to how nulls are handled with JSONRequired.
Previously, when null values were passed in a record, or on one of its
primitive elements, marked with JSONRequired, the GWS sent null.
Now serialization error-15807
will be raised if a null value is sent. Where previously you did not have an option
to allow null values, you must now review your code to explicitly allow null values.
To explicitly allow a null value, you must set the json_null="null" attribute on the relevant field, or set the serializeNullAsDefault option for the The json.Serializer class to allow nulls.
For more information about JSONRequired attribute, go to JSONRequired.
New HttpRequest methods dynamically override FGLPROFILE entries
Starting from FGLGWS 5.01.00, new methods in the HttpRequest class have been
implemented to allow you to override configurations in FGLPROFILE dynamically at runtime.
Calling setCertificateAndKey() overrides configuration for certificates that might be set in FGLPROFILE. Calling the setCipher() and setVerifyServer() override other parameters that may be set in FGLPROFILE.
While clearing a parameter using clearCertificateAndKey(), clearCipher(), and clearVerifyServer() resets values to the ones configured in FGLPROFILE.
For details, go to com.HttpRequest methods: connection options.
New xml.keystore.cadir entry in FGLPROFILE for XML signature verification
Starting from FGLGWS 5.01.00, an xml.keystore.cadir entry can be used to specify
a directory for all trusted X509 certificates to be used during XML signature verification.
Previously, you could only specify a priority list of certificates with the
xml.keystore.calist entry.
Now, xml.keystore.cadir allows you to provide all the CA certificates in a
directory. You can continue to use the xml.keystore.calist as before; as files in
the "cadir" directory will be appended to those in xml.keystore.calist.
For more details, go to FGLPROFILE entries for XML configuration.
New json.Serializer.getLastErrorDescription() method has improved error
messaging
Starting from FGLGWS 5.01.01, a new method in the json.Serializer class has been
implemented to allow you return last generated serialization error message.
Calling json.Serializer.getLastErrorDescription returns a more
complete message than sqlca.sqlerrm. It will return the name of the class to
identify the source of the error, the name of the fields, when known, along with a detailed
description of the error.
Specific exception -15582 for status code not in the range 200 - 299
Starting from FGLGWS 5.00.00 and 5.01.02, the GWS method com.WebServiceEngine.SetRestStatus raises a specific error code -15582, when the status code is not in the range 200 - 299.
Specific exception -15583 when setting a LANG value not recognized by iconv
Starting from FGLGWS 5.01.02, the GWS raises a specific error code -15583 when the
LANG value is not a codeset recognized by iconv.
Register web services and resources from a package
Starting from FGLGWS 5.01.02, the GWS supports package-style modules in the
com.WebServiceEngine.RegisterRestService() and
com.WebServiceEngine.RegisterRestResources() methods.
No action needs to be taken on your part, but if you have previously wanted to use a Genero BDL package when registering web services, this is now possible.
For more information on how to use this feature, go to com.WebServiceEngine.RegisterRestService or com.WebServiceEngine.RegisterRestResources.
New json.Serializer option for handling implicit conversion
To implement strict JSON schema validation while allowing flexibility when needed, we are introducing an option for implicit conversions during JSON to BDL deserialization.
Starting with FGLGWS 5.01.03, the global option allowImplicitConversion in
json.Serializer permits implicit type conversion for
INTEGER/NUMBER(DECIMAL), BOOLEAN, and
STRING values in an array. For example, a boolean value can be represented as
1, 0, true, false,
"true", "false", or "1",
"0".
You can now use CALL json.Serializer.setOption("allowImplicitConversion", 1) in
your server module to enable this option and avoid deserialization errors related to type
mismatches.
For details, go to json.Serializer options.
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.
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.
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.
Discontinued support for OCSP
We are discontinuing support for the Online Certificate Status Protocol (OCSP) due to the decision by several Certificate Authorities to phase out support for this protocol in web services. However, please note that the OCSP functionality will remain intact within our product, allowing you to continue using this feature as part of your secure communications.
For more information on OCSP, go to Enable OCSP.
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 5.01.07, 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.
External DTD of XML request and response bodies
Starting from FGLGWS 5.01.07, 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 5.01.07, 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.
Changes to how GWS handles an invalid HTTP request
Starting from FGLGWS 5.01.07, 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.
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 5.01.06 and GAS 5.01.05