WSName

Specify alternative names for parameters in a REST function.

Syntax

WSName=" description "

WSName is an optional attribute.

Usage

Use this attribute to specify names for parameters in a REST function. In general, you do not need to use WSName. Consider using it to improve the readability of input parameters or to format the data returned in the response.

Example 1: Providing an alternative name

You need to use WSName to provide the required name, if the input parameter name cannot be used as a variable name in your REST function.

For example, if you need to pass parameters for the Genero Application Server environment, you will need to use WSName. These variables (for example, X-FourJs-XXX) have hyphens, which are not allowed in Genero BDL variables. WSName allows you to use a parameter name that is BDL friendly but provide the required name of the variable in the header.
PUBLIC FUNCTION getRemoteAddress (remote_ip_addr STRING 
   ATTRIBUTE(WSHeader, WSOptional, WSName="X-FourJs-Environment-Variable-REMOTE_ADDR") )
In the HTTP request, there will be a header named "X-FourJs-Environment-Variable-REMOTE_ADDR", not "remote_ip_addr". In your function, you reference the variable using the "remote_ip_addr" variable name.

Example 2: Providing a user-friendly parameter name

You would consider setting the WSName attribute clause of a parameter, if the parameter name is not obvious or user-friendly.

For example, if the parameter references a field name in a database table that is abbreviated, or could be ambiguous in your function, WSName provides you with an option to provide a clearer name.

PUBLIC FUNCTION getUsers(reg STRING ATTRIBUTE(WSQuery, WSOptional, WSName="region"),
     ccode STRING ATTRIBUTE(WSHeader, WSName="country") )
In the HTTP request:
  • There will be a header named "country", not "ccode".
  • In the URL to call the REST function, you must use the value specified by WSName (not the parameter name) for the query:

    http://host:port/gas/ws/r/MyService/users?region=alsace

Example 3: Formatting output data

You can use WSName to format the output data. It allows you to override the default naming convention ("rv0", "rv1", etc., ) that is otherwise output at runtime. By specifying a more recognizable name for the data, you improve the readability of the output.

In the example, the attribute names the array "Users". This name will appear as the root path for the output in JSON, or the root tag for the output in XML.

TYPE userType RECORD ... END RECORD

PUBLIC FUNCTION getUsers()
  ATTRIBUTES (WSGet, 
              WSPath="/users",
              WSDescription="Get users resource ",
              WSThrows="400:Invalid,404:NotAvailable" )
  RETURNS (DYNAMIC ARRAY ATTRIBUTE(WSName = "Users") OF
        userType ATTRIBUTES(WSMedia = "application/json, application/xml"))
  
    DEFINE regionList DYNAMIC ARRAY OF userType
      
    # ... function code  ...

    RETURN regionList
END FUNCTION