software AG 开发者接口示例

Variables usage via request and response transformation policies and other policies in API Gateway ================================================================================================== Authors: Chandrasekaran, Vallab (vac@softwareag.com) Supported Versions: 10.7 and above (For versions 10.3 and 10.5, **[refer this...](http://techcommunity.softwareag.com/pwiki/-/wiki/Main/Request%20and%20Response%20Transformation%20policies%20in%20API%20Gateway)**) --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Overview of the tutorial ======================== Right from the initial versions of API Gateway, there are options like Invoke webmethods IS policy in API Gateway that helps the API Provider to plugin custom logics, such as transformation of request and response contents, in the mediation flow of an API.  However the transformation policies introduced in version 10.2 provide a better and easy configuration of transformations based on conditions to a greater extent. The Provider does't need to create an IS service explicitly, instead they can use the simple UI configurations in the transformation policies to achieve the same use cases. Using the concept called "variables", a provider can access and evaluate (a condition) and/or modify the contents of request or response like headers, query parameters, path parameters, HTTP method, status code, status message and payload etc. In 10.7, usage of these "variables" are enhanced further and extended to be used across all other policy actions as well. Required knowledge ================== The reader is expected to have a basic understanding of API Gateway and policy enforcement. Why? ==== API Gateway forwards the incoming requests from the client to the native service, and forwards the response from the native service back to the client. Now if the API Provider wants to modify the request before forwarding the request to native service, they can make use of Request Transformation policy. Similarly Response Transformation policy can be used to modify the response before forwarding it to the client.  For example, consider an usecase like, the native service wants to identify all incoming requests via the API Gateway. For that usecase, the API provider can simply configure the Request Transformation policy to add a header which is uniquely identifiable by the native server and using that the native server identifies the requests sent via API Gateway.  What are Variables and what's new in 10.7 ----------------------------------------- Right from the introduction of the request and response transformation policies (in 10.2), these policies uses a concept called "Variables". Variables are nothing but a defined set of syntaxes that can be used to access or modify the contents of request or response (such as headers, payload, etc). For example, we can use the syntax ${request.headers.xyz} to access the value of the request header "xyz" or modify it's value.  In 10.7, usage of these variables are enhanced further. Following are the enhancements supported from 10.7 1. Until 10.5, variables are supported only in request and response transformation policies and custom extension policy. Variables can now be accessed across all stages and most of the policy actions and policy parameters support this.  2. Simple aliases can also be accessed via variables. You can now access the value of the simple aliases in any policy action using the variables syntax. 3. System and custom variables (supported in earlier versions via Invoke IS Service and known as context variables) can now be defined or accessed in any policy action. 1. System variables (also called as system context variables) are variables which can be used to access the values computed  by API Gateway during the runtime. The values of these variables cannot be modified. For example, you can access the value of the IP address from which the request is received using the syntax ${inboundIP} but you are not allowed to modify the value of this.  2. Custom variables are the set of variables which are defined by API provider at policy level and can be accessed at other policies downstream. Custom variables can be configured using the "Custom Variables" option in custom extension policy.  4. Many new variables are added that allow access to more information at policy level. 5. Adding custom fields to transactional events.  Adding custom fields to the transactional events are supported from 10.3 via Invoke IS Service policy. Now you have an option to do that without having to write an IS Service for this purpose. 6. Modify the request/response payload via request/response transformation policy respectively. 7. Access to request variables in response and error stage. From 10.7, you can use the ${request....} syntax to access the request variables in response and error stage. We will see about these enhancements in detail in below sections.  Prerequisite steps ================== * Install advanced edition of API Gateway 10.7 or later Details ======= Variables --------- Variables are nothing but a defined set of syntaxes that can be used to access or modify the contents of request or response (such as headers, payload, etc). For example, we can use the syntax ${request.headers.xyz} to access the value of the request header "xyz" or modify it's value.  Let's define the syntaxes and guidelines for the usage of variables. We will use these syntaxes in the next sections where will try to achieve some usecases using policies like Transformation policy.  ### Variable types We can broadly classify the variables under the below types. 1. **Request variables -** for accessing/modifying the value of the request content. For example, access a particular header. 2. **Response variables** - for accessing/modifying the value of the response content. For example, modify the status code before sending to client. 3. **System variables -** System variables (also called as system context variables) are variables which can be used to access the values computed  by API Gateway during the runtime. For example, you can access the value of the IP address from which the request is received using the syntax ${inboundIP} but you are not allowed to modify the value of this.  4. **Custom variables** \- An API provider can define any custom variable with their preferred name and assign a value to the variable using custom extension policy. The value of those custom variables can be accessed at other policies downstream using the variables syntax. ### Request and response variables - syntax The request variables and response variables generally can be accessed using one of the below syntax formats * ${paramStage.paramType.name} * For example, ${request.headers.xyz} is used to access the request header "xyz" * ${paramStage.paramType.queryType\[query\]}  * For example, ${response.payload.jsonPath\[$.cardDetails.number\]} is used to apply the jsonPath "$.cardDetails.number" on response payload. * ${paramStage.paramType} * For example, ${response.statusCode} to access the response status code. The below table provides the definition and possible values for the keywords like paramStage, paramType and queryType. |**Keyword**| **Usage** | | --------- | --------------------------------- | |paramStage |Defines the stage which we are referring. Possible values are,<br/><br/>1. request <br/>2. response| |paramType |Defines the specific parameter of the request/response whose value we are accessing or transforming. <br/>Possible values are,<br/><br/>1. payload <br/>2. headers <br/>3. query (applicable only for REST)<br/>4. path (applicable only for REST)<br/>5. httpMethod (applicable only for REST)<br/>6. statusCo