[DX-1142, TT-11620] Updated virtual endpoint and JS docs

tyk-docs/content/advanced-configuration/compose-apis/demo-virtual-endpoint.md

@@ -1,29 +1,140 @@
 ---
-date: 2017-03-23T18:08:16Z
-title: Virtual Endpoint Demonstration
-menu:
-  main:
-    parent: "Compose APIs"
-weight: 2 
+title: Virtual Endpoint examples
+tags:
+    - JavaScript
+    - JS
+    - middleware
+    - scripting
+    - JSVM
+    - examples
+    - virtual endpoint
+description: Examples of Virtual Endpoints
+date: "2017-03-23T18:08:16Z"
+aliases:
+    - /advanced-configuration/compose-apis/sample-batch-funtion/
 ---
 
-## Set up the Virtual Endpoint
+Here we offer some examples to demonstrate valid use of JavaScript within Virtual Endpoints. You can either copy and paste the JavaScript code into the code editor in the Tyk Dashboard API Designer, or create a file and place it in a subdirectory of the Tyk configuration environment (for example under the `middleware` folder in your Tyk installation).
 
-Virtual Endpoints are defined per API on an endpoint level. To set up a Virtual Endpoint:
+## Example 1: Accessing Tyk data objects
 
-1. From the **Endpoint Designer**, Add a new Endpoint.
-2. From the Plugins drop-down list, select **Virtual Endpoint**.
-3. From the Virtual Endpoint settings, add a unique name in the **JS function to call** option. You should also use the same name inside the function code. For this demo, we will use `myVirtualHandlerGetHeaders`.
+In this example, we demonstrate how you can access different [external Tyk objects]({{< ref "plugins/supported-languages/javascript-middleware/middleware-scripting-guide#accessing-external-and-dynamic-data" >}}) (API request, session key, API definition).
 
-Every line in the script gives an example of a functionality usage:
+1. Enable the Virtual Endpoint middleware on an endpoint of your API and paste this JavaScript into the API Designer (or save in a file and reference it from the middleware config):
 
-* How to get form param
-* How to get specific key inside json variable
-* The structure of request object with `Body`, `Headers`, (need to add session object examples)Using `TykMakeHttpRequest`, and the json it returns - `.Code` and `.Body`.
+```javascript
+function myFirstVirtualHandler (request, session, config) {
+  log("Virtual Test running")
+
+  log("Request Body: " + request.Body)
+  log("Session: " + JSON.stringify(session.allowance))
+  log("Config: " + JSON.stringify(config.APIID))
+  log("param-1: " + request.Params["param1"]) // case sensitive
+  log("auth Header: " + request.Headers["Authorization"]) // case sensitive
+
+  var responseObject = {
+    Body: "VIRTUAL ENDPOINT EXAMPLE #1",
+    Headers: {
+      "x-test": "virtual-header",
+      "x-test-2": "virtual-header-2"
+    },
+    Code: 200
+  }
+
+  return TykJsResponse(responseObject, session.meta_data)   
+}
+log("Virtual Test initialised")
+```
+
+2. Make a call to your API endpoint passing a request body, a value in the `Authorization` header and a query parameter `param1`.
+
+3. The virtual endpoint will terminate the request and return this response:
+
+```http
+HTTP/1.1 200 OK
+Date: Thu, 29 Feb 2024 17:39:00 GMT
+Server: tyk
+X-Test: virtual-header
+X-Test-2: virtual-header-2
+Content-Length: 27
+Content-Type: text/plain; charset=utf-8
+
+VIRTUAL ENDPOINT EXAMPLE #1
+```
+
+4. The gateway logs will include:
+
+```text
+time="" level=info msg="Virtual Test running" prefix=jsvm type=log-msg
+time="" level=info msg="Request Body: <your-request-body>" prefix=jsvm type=log-msg
+time="" level=info msg="Session: <allowance-from-your-session-key>" prefix=jsvm type=log-msg
+time="" level=info msg="Config: <your-APIID>" prefix=jsvm type=log-msg
+time="" level=info msg="param-1: <your_query_parameter>" prefix=jsvm type=log-msg
+time="" level=info msg="auth Header: <your-auth-header>" prefix=jsvm type=log-msg
+```
+
+## Example 2: Accessing custom attributes in the API Definition
+
+You can add [custom attributes]({{< ref "plugins/supported-languages/javascript-middleware/middleware-scripting-guide#passing-custom-attributes-to-middleware" >}}) to the API definition and access these from within your Virtual Endpoint.
+
+1. Add the following custom attributes to your API definition:
+
+```json
+{
+  "string": "string",
+  "map": {
+    " key": 3
+  },
+  "num": 4
+}
+```
+
+2. Enable the Virtual Endpoint middleware on an endpoint of your API and paste this JavaScript into the API Designer (or save in a file and reference it from the middleware config):
+
+```js
+function mySecondVirtualHandler (request, session, config) {      
+  var responseObject = {
+    Body: "VIRTUAL ENDPOINT EXAMPLE #2",
+    Headers: {
+      "foo-header": "bar",
+      "map-header": JSON.stringify(config.config_data.map),
+      "string-header": config.config_data.string,
+      "num-header": JSON.stringify(config.config_data.num)
+    },
+      Code: 200
+  }
+  return TykJsResponse(responseObject, session.meta_data)
+}
+```
+
+3. Make a call to your API endpoint.
+
+4. The virtual endpoint will terminate the request and return this response:
+
+```http
+HTTP/1.1 200 OK
+Date: Thu, 29 Feb 2024 17:29:12 GMT
+Foo-Header: bar
+Map-Header: {" key":3}
+Num-Header: 4
+Server: tyk
+String-Header: string
+Content-Length: 26
+Content-Type: text/plain; charset=utf-8
+
+VIRTUAL ENDPOINT EXAMPLE #2
+```
+
+## Example 3: Advanced example
 
-Paste the following code in the **Code editor**.
+In this example, every line in the script gives an example of a functionality usage, including:
 
-```{.json}
+- how to get form param
+- how to get to a specific key inside a JSON variable
+- the structure of the request object
+- using `TykMakeHttpRequest` to make an HTTP request from within the virtual endpoint, and the json it returns - `.Code` and `.Body`.
+
+```js
 function myVirtualHandlerGetHeaders (request, session, config) {
   rawlog("Virtual Test running")
 
@@ -58,7 +169,7 @@ function myVirtualHandlerGetHeaders (request, session, config) {
   var bodyObject = JSON.parse(usableResponse.Body);
 
   var responseObject = {
-    //Body: "THIS IS A  VIRTUAL RESPONSE",
+    //Body: "THIS IS A VIRTUAL RESPONSE",
     Body: "yo yo",
     Headers: {
       "test": "virtual",
@@ -72,23 +183,20 @@ function myVirtualHandlerGetHeaders (request, session, config) {
   return TykJsResponse(responseObject, session.meta_data)   
 }
 ```
-{{< note success >}}
-**Note**  
-
-Another option, instead of the steps above, you can use this Gist to import the API definition - [API Definition Import](https://gist.github.com/letzya/5b5edb3f9f59ab8e0c3c614219c40747)
-{{< /note >}}
 
+#### Running the Advanced example
 
-The virtual function is `base64` encoded in the `function_source_uri` field.
+You can find a Tyk Classic API definition [here](https://gist.github.com/letzya/5b5edb3f9f59ab8e0c3c614219c40747) that includes the advanced example, with the JS encoded `inline` within the middleware config for the `GET /headers` endpoint.
 
-## Demonstrating the Virtual Endpoint
+Create a new Tyk Classic API using that API definition and then run the following command to send a request to the API endpoint:
 
-Run the following command:
-`curl http://tyk-gateway:8080/testvirtualendpoint2/headers -H "location: /get" -v`
+```bash
+curl http://tyk-gateway:8080/testvirtualendpoint2/headers -H "location: /get" -v
+```
 
 This should return the following:
 
-```
+```http
 Trying 127.0.0.1...
 TCP_NODELAY set
 Connected to tyk-gateway (127.0.0.1) port 8080 (#0)
@@ -104,19 +212,18 @@ Date: Fri, 08 Jun 2018 21:53:57 GMT
 Server: tyk
 Test: virtual
 Test-2: virtual
-X-Ratelimit-Limit: 0
-X-Ratelimit-Remaining: 0
-X-Ratelimit-Reset: 0
 Content-Length: 5
 Content-Type: text/plain; charset=utf-8
 
 Connection #0 to host tyk-gateway left intact
 yo yo
 ```
 
-## Checking the Tyk Gateway Logs
+#### Checking the Tyk Gateway Logs
 
-```
+The `log` and `rawlog` commands in the JS function write to the Tyk Gateway logs. If you check the logs you should see the following:
+
+```text
 [Jun 13 14:45:21] DEBUG jsvm: Running: myVirtualHandlerGetHeaders
 Virtual Test running
 [Jun 13 14:45:21]  INFO jsvm-logmsg: Request Session: {"access_rights":null,"alias":"","allowance":0,"apply_policies":null,"apply_policy_id":"","basic_auth_data":{"hash_type":"","password":""},"certificate":"","data_expires":0,"enable_detail_recording":false,"expires":0,"hmac_enabled":false,"hmac_string":"","id_extractor_deadline":0,"is_inactive":false,"jwt_data":{"secret":""},"last_check":0,"last_updated":"","meta_data":null,"monitor":{"trigger_limits":null},"oauth_client_id":"","oauth_keys":null,"org_id":"","per":0,"quota_max":0,"quota_remaining":0,"quota_renewal_rate":0,"quota_renews":0,"rate":0,"session_lifetime":0,"tags":null} type=log-msg
@@ -138,3 +245,60 @@ Virtual Test ended
 [Jun 13 14:45:22] DEBUG JSVM Virtual Endpoint execution took: (ns) 191031553
 ```
 
+## Example 4: Aggregating upstream calls using batch processing
+
+One of the most common use cases for virtual endpoints is to provide some form of aggregate data to your users, combining the responses from multiple upstream service calls. This virtual endpoint function will do just that using the batch processing function from the [JavaScript API]({{< ref "plugins/supported-languages/javascript-middleware/javascript-api" >}})
+
+```js
+function batchTest(request, session, config) {
+  // Set up a response object
+  var response = {
+    Body: "",
+    Headers: {
+      "test": "virtual-header-1",
+      "test-2": "virtual-header-2",
+      "content-type": "application/json"
+    },
+    Code: 200
+  }
+
+  // Batch request
+  var batch = {
+    "requests": [
+      {
+        "method": "GET",
+        "headers": {
+          "x-tyk-test": "1",
+          "x-tyk-version": "1.2",
+          "authorization": "1dbc83b9c431649d7698faa9797e2900f"
+        },
+        "body": "",
+        "relative_url": "http://httpbin.org/get"
+      },
+      {
+        "method": "GET",
+        "headers": {},
+        "body": "",
+        "relative_url": "http://httpbin.org/user-agent"
+      }
+    ],
+    "suppress_parallel_execution": false
+  }
+
+  log("[Virtual Test] Making Upstream Batch Request")
+  var newBody = TykBatchRequest(JSON.stringify(batch))
+
+  // We know that the requests return JSON in their body, lets flatten it
+  var asJS = JSON.parse(newBody)
+  for (var i in asJS) {
+    asJS[i].body = JSON.parse(asJS[i].body)
+  }
+
+  // We need to send a string object back to Tyk to embed in the response
+  response.Body = JSON.stringify(asJS)
+
+  return TykJsResponse(response, session.meta_data)
+
+}
+log("Batch Test initialised")                
+```