The API requester Gradle plug-in properties and options

Define attributes in the z/OS Connect API requester Gradle plug-in options.yaml file before you run the build from the command line.

The following API requester Gradle plug-in properties and options are available to customize the generation of your API requester artifacts from an OpenAPI document.

zosConnect-3.0 Applies to zosConnect-3.0.

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

Mandatory attributes

language

Specifies the language for the code generation.

COBOL: The language for the code generation is COBOL.
PLI: The language for the code generation is PLI.

projectType

Specify whether the properties and options to customize the generation of your artifacts from an OpenAPI definition are for an API provider or an API requester project.

Optional attributes

additionalPropertiesSize

Specifies the maximum size for each of the additional JSON properties that are not explicitly defined in the properties section of an OpenAPI document. The value of this parameter can be a positive integer in the range of 16 - 32767. The default value is 255. A field of the specified size is generated into the language structures that are produced by the Gradle plug-in. The generated language structures are able to support up to 20 additional properties.

apiKeyMaxLength

Specifies the maximum length of the values set for API keys. The value of this parameter can be a positive integer in the range 1 - 32767. The default value is 255.

apiKeyParmNameInCookie

Specifies the name of an API key that is sent in a cookie. The value of this parameter can be a comma-separated list of client ID and client secret cookie names. The actual client ID and client secret values are set in the z/OS application.

For example, you can set apiKeyParmNameInCookie: client_id, client_secret when a client ID and a client secret are used to protect an API.

Note: Only one of apiKeyParmNameInHeader or apiKeyParmNameInQuery or apiKeyParmNameInCookie can be specified. If both an OpenAPI document and z/OS Connect Gradle plug-in properties are used to define API key names, then only the security definition in the document is used to generate the names of the API key parameters that are in the request data structures.

apiKeyParmNameInHeader

Specifies the name of an API key that is sent as a request header. The value of this parameter can be a comma-separated list of client ID and client secret header names. The actual client ID and client secret values are set in the z/OS application.

For example, you can set apiKeyParmNameInHeader: client_id, client_secret when a client ID and a client secret are used to protect an API.

apiKeyParmNameInQuery

Specifies the name of an API key that is sent in a query string. The value of this parameter can be a comma-separated list of client ID and client secret query names. The actual client ID and client secret values are set in the z/OS application.

For example, you can set apiKeyParmNameInQuery: client_id,client_secret when a client ID and a client secret are used to protect an API.

apiName

Specifies a value to override the name and the context root of the generated API requester WAR file. If not specified, the Gradle project name is used. The Gradle project name can be set by the rootProject.name property in the settings.gradle file. If rootProject.name is not specified, the directory name is used.

The context-root is used by the Host API to determine the URL to call for the application and therefore must remain unchanged after the Gradle plug-in is run. Overriding the value of the context-root in the Liberty server.xml is not supported.

characterMultiplier

Specifies the number of bytes allowed for each character. The value of this parameter can be a positive integer in the range of 1 - 2,147,483,647. All nonnumeric character-based mappings are subject to this multiplier. Binary, numeric, zoned, and packed decimal fields are not subject to this multiplier. The default value is 1.

This parameter can be useful if, for example, you are planning to use DBCS characters where you might opt for a multiplier of 3 to allow space for potential shift-out and shift-in characters around every double-byte character at run time.

When you set runtimeCodePage=1200 (indicating UTF-16), the only valid values for characterMultiplier are 2 or 4. When you use UTF-16, the default value is 2. Use characterMultiplier=2 when you expect application data to contain characters that require one UTF-16 encoding unit. Use characterMultiplier=4 when you expect application data to contain characters that require two UTF-16 encoding units.

Note: Setting characterMultiplier to 1 does not preclude the use of DBCS characters, and setting it to 2 does not preclude the use of UTF-16 surrogate pairs. However, if wide characters are routinely used, then some valid values will not fit into the allocated field. If a larger characterMultiplier value is used, it might be possible to store more characters in the allocated field than are valid in the XML. Take care to conform to the appropriate range restrictions.

characterVarying

Specifies how variable-length character data is mapped to the language structure.

NO: Variable-length character data is mapped as fixed-length strings.

NULL: Variable-length character data is mapped to null-terminated strings. This value must be in quotation marks. For example, "NULL".

YES: In COBOL, variable-length character data is mapped to an equivalent representation that consists of two related elements: the data-length and the data.

The default is YES.

characterVaryingLimit

Specifies the maximum size of binary data and variable-length character data that is mapped to the language structure.

When characterVarying is set to NO or NULL the value of this parameter can be a positive integer in the range of 1 to 16777214.

When characterVarying is set to YES the value of this parameter can be a positive integer in the range of 1 to 32767.

The default is 32767.

characterWhiteSpace

Specify how white space in values of type string are handled.

COLLAPSE: Leading, trailing, and embedded white space is removed and all tabs, new lines, and consecutive spaces are replaced with single space characters.

REPLACE: Any tabs or new lines are replaced with the appropriate number of spaces.

PRESERVE: Retains any white space in the data value.

TRIM: Leading and trailing white space is removed.

The default is COLLAPSE.

Note: This parameter does not apply to fields with a format of date-time, uri, base64Binary, or hexBinary, where white space is always collapsed.

connectionRef

Specifies the name of the connection to identify the RESTful endpoint. If you do not set connectionRef in the Gradle plug-in properties file, you must set a value in the appProperties property of the webApplication element in the server.xml file. Otherwise, an error occurs. For more information, see Configuring zosConnect-3.0 to support API requesters

dateTimeFormat

Specifies how JSON date-time elements are mapped to the data structure.

PACKED15: Any JSON date-time element is processed as a timestamp and is mapped to absolute format.

STRING: The JSON date-time element is processed as text.

The default is PACKED15.

dataTruncation

Specifies whether variable-length data is tolerated in a fixed-length field structure.

DISABLED: If the data is less than the fixed length that z/OS Connect is expecting, z/OS Connect rejects the truncated data and issues an error message.

ENABLED: If the data is less than the fixed length that z/OS Connect is expecting, z/OS Connect tolerates the truncated data and processes the missing data as null values.

The default is DISABLED.

defaultCharacterMaxLength

Specifies the default array length of character data for mappings where no length is implied in the JSON schema document.

When characterVarying is set to YES the value of this parameter can be a positive integer in the range of 1 to 32767.

When characterVarying is set to NO or NULL the value of this parameter can be a positive integer in the range of 1 to 16777214.

The default is 255.

defaultFractionDigits

Specifies the default number of fraction digits to use on a JSON decimal schema type. For COBOL, the valid range is 0-17, or 0-30 if parameter wideComp3 is set. For PL/I, the valid range is 0-30.

The default value is 3.

defaultRequestMediaType

When more than one media type is available in the OpenAPI document for a specific operation, and no MIME type is specified for that operation in the options.yaml file, the defaultRequestMediaType is used instead. If the defaultRequestMediaType is also not specified, the system defaults whenever available to JSON MIME types such as "application/json" or “application/myapi+json”.

defaultResponseMediaType

When more than one media type is available in the OpenAPI document for a specific operation and response code combination, and no MIME type is specified for that combination in the options.yaml file, the defaultResponseMediaType is used instead. If the defaultResponseMediaType is also not specified, the system defaults whenever available to JSON MIME types such as "application/json" or “application/myapi+json”.

extendFieldNames

The default is false.

When long JSON property names are represented in generated language structures the maximum size is two less than the language limit, which is 30 for COBOL or 31 for PL/I. This is to allow a two-character space to be used for a numerical suffix when field names clash.

Setting extendFieldNames to true will allow generated language structure fields to use the full language length. However, should a field name clash be detected, then the field name is trimmed by two and the numerical suffix added.

generatedCodePage

Specifies the code page that is used for the generated language structure and API information file. The value is a runtimeCodePage number or Java™ code page number. If this parameter is not specified, the code page of the system that the Gradle plug-in is running on is used. For example, you might specify generatedCodePage=037 for EBCDIC.

inlineMaxOccursLimit

(New for Data Areas.) Specifies the size limit for an array before it is upgraded to a data area. The default value is 21 for operations that include additionalProperties, otherwise the default value is 1. If you specify inlineMaxOccursLimit=5, and the array has three elements, it remains an array. If the array has seven elements, it is transformed into a Data Area instead.

groupSuffix

The default is false.

In generated COBOL language structures where fields represent JSON object properties, the JSON property name can be used in multiple locations, particularly for variable length strings. In this case, a numerical suffix is added to the clashing field name.

For example,

06 myProperty.
 09 myProperty-length PIC S9999.
 09 myProperty2 PIC X(255).

For code readability, it may be desirable to have the actual string field that is named after the JSON property.

To avoid this name clash, set groupSuffix to true. This option sets the group level language structure element suffix with Grp and simple type arrays with the Arr suffix. As a result, the string field representing the JSON property available to use the JSON property name as the field name, subject to programming language rules.

For example,

06 myPropertyGrp.
 09 myProperty-length PIC S9999.
 09 myProperty PIC X(255).

nameTruncation

Specifies how JSON names are truncated. nameTruncation can be set LEFT or RIGHT. By default, names are truncated from the right.

operations

Specifies the list of operations from the OpenAPI document to be processed. Any operation not in the list is ignored. If this property is not specified, all operations are processed. This property can be specified as a comma-separated list. For example,

operations=employeesIdGet,
employeesIdDelete

requestMediaType

Specifies the MIME type to use for the request when more than one is set in the OpenAPI document. This value is used to validate the Content-Type request header. The value of the requestMediaType parameter is a comma-separated list of MIME types for a specific operation. For example,

requestMediaType:
employeesIdGet(application/json), employeesIdDelete(application/json)

When more than one type is available in the OpenAPI 2.0 document and no MIME type is specified for a specific operation in the options.yaml file, the system defaults when possible to JSON MIME types such as "application/json" or “application/myapi+json”. If no such type is available for that operation in the OpenAPI document, the Gradle build fails with an error.

To change the default, see defaultRequestMediaType.

requesterExtension

Specifies a file extension for the generated request data structure, response data structure, and API information files. For example, if language is specified as COBOL and requesterExtension is specified as cpy the following files will be generated for the first operation: API00I01.cpy, API00P01.cpy and API00Q01.cpy.

The default is no file extension.

requesterPrefix

Specifies a prefix for the generated request data structure, response data structure, and API information file. The value of this parameter has a maximum length of 3 characters. The first character must be either a letter or one of the following three special characters: # @ $. The remaining characters can be letters, numbers, or one of the following special characters: # @ $.

The default is API.

responseMediaType

Specifies the MIME type to use for the response when more than one is set in the OpenAPI document. This value is used to validate the Content-Type response header. The responseMediaType is a comma-separated list of MIME types for a specific operation and response code. For example,

responseMediaType:
employeesIdGet/200(application/json), employeesIdGet/404(application/json)

When more than one type is available in the OpenAPI document, and no MIME type is specified for a specific operation in the options.yaml file, the system defaults when possible to JSON MIME types such as "application/json" or “application/myapi+json”. If no such type is available for that operation and response code in the OpenAPI document, the Gradle build fails with an error.

To change the default, see defaultResponseMediaType.

runtimeCodePage

Specifies the CCSID that is used at run time to encode character data in the application language structure. By default, runtimeCodePage is set to CP037. The CCSID list that the Gradle plug-in supports is the same as the one supported by the CICS® conversion program.

For more information about the supported list, see CICS-supported conversions in the CICS Transaction Server for z/OS 6.x documentation.

sendContentTypeForEmptyBody

Specify whether to send a Content-Type header on API endpoint requests that have no payload. The default, sendContentTypeForEmptyBody is set to true, and the MIME type is specified by the content field of the requestBody object in OpenAPI 3.0 specification.

If sendContentTypeForEmptyBody is set to false, no Content-Type header is sent on API endpoint requests that have no payload.

shortSuffix

Specifies how certain property suffixes are generated in the language structures.

No: The suffixes -existence, -patch-operation, and -patch-item are used.

Yes: The suffixes -exists, -pchop, and -pchitem are used. This then provides more space for the property name within the generated language structures.

The default is No.

wideComp3

For COBOL only. Specifies the maximum size of the packed decimal variable length in the COBOL language structure.

NO: The packed decimal variable length is limited to 18 when the COBOL language structure type COMP-3 is generated. If the packed decimal size is greater than 18, message DFHPI9022W is issued to indicate that the specified type is restricted to a total of 18 digits.

YES: The maximum size of 31 is supported when the COBOL language structure type COMP-3 is generated.

The default is NO.