You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/fundamentals/best-practices-api-proxy-design-and-development). info

In this topic you will learn how to use JavaScript to dynamically add HTTP headers to a
response message and how to parse a JSON response and return a subset of its properties to the
the requesting app.

## Download and try out the sample code

> [!NOTE]
> **Sample:** **Sample code:** We recommend that you download and try out this topic's sample code from GitHub. The sample is called **javascript-cookbook** , which you can find in the [doc-samples folder](https://github.com/apigee/api-platform-samples/tree/master/doc-samples) in the Apigee Edge API Services samples repository in GitHub. For information on downloading Apigee samples, see [Using the sample API proxies](https://docs.apigee.com/api-platform/samples/using-samples).
>
> Instructions for deploying the API proxy and consuming the API are provided in the [README](https://github.com/apigee/api-platform-samples/blob/master/doc-samples/javascript-cookbook/README.md) file that comes with the sample. You can also find brief deployment
> instructions here: [Using the sample API
> proxies](https://docs.apigee.com/api-platform/samples/using-samples).

## About this cookbook example

This cookbook example illustrates an API proxy pattern in which you implement API behavior in
JavaScript. The JavaScript examples are designed to show you how to work with simple variables
and message content. One sample shows you how to *get* and *set* variables. The second
example shows you how to parse JSON and construct a message from the result.

Two JavaScript samples are in the API proxy:

- **`setHeaders.js`**: This JavaScript gets the values of a few variables that are set when an API proxy is invoked. The JavaScript adds those variables to the response message so that you can see their values for each request that you make.
- **`minimize.js`**: This JavaScript shows you how to work with message content. The idea behind this sample is that a service often returns more data than is necessary. So, the JavaScript parses the response message, extracts a few interesting properties, and then uses them to build the content of the response message.

The code for `setHeader.js`:

```javascript
context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));
```

The code for `minimize.js`:

```javascript
// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);
```

You can access flow variables in JavaScript through the context object. This object is part of
the Edge JavaScript object model. For details about the object model, see [JavaScript object model](https://docs.apigee.com/api-platform/reference/javascript-object-model).

> [!IMPORTANT]
> **Tip:** A useful exercise once you have the JavaScript working, is to modify these fields to use other values. For example, you can try changing the variable that sets the HTTP header by selecting a different variable from the list of [Variables reference](https://docs.apigee.com/api-platform/reference/variables-reference).

> [!NOTE]
> **Note:** The sample proxy uses a policy of type XMLToJSON to convert the XML-formatted response into JSON. When working with JavaScript, you can always use this policy type to transform XML into JSON, making it easier for you to work with message content in JavaScript.

## Before you begin

Before you explore this cookbook example, you should also be familiar with these fundamental
concepts:

- What policies are and how to attach them to proxies. For a good introduction to policies, see [What's a
  policy?](https://docs.apigee.com/api-platform/develop/policy-attachment-and-enforcement).
- The structure of a proxy flow, as explained in [Configuring flows](https://docs.apigee.com/api-platform/fundamentals/flow-configurations). Flows let you specify the sequence in which policies are executed by an API proxy. In this example, several policies are created and added to an API proxy flow.
- How an API proxy project is organized on your filesystem, as explained in [API proxy configuration reference](https://docs.apigee.com/api-platform/reference/api-proxy-configuration-reference).
- A working knowledge of XML, JSON and JavaScript. In this example, you build out the API proxy and its policies with XML files that reside on the filesystem.

If you have downloaded the sample code, you can locate all of the files discussed in this
topic in the **javascript-cookbook** sample folder. The following sections discuss
the sample code in detail.

## Understanding the proxy flow

To get JavaScript to execute in an API proxy, you have to attach it to a flow using a policy
attachment called a 'Step'. A policy of type Javascript (note capitalization) simply contains a
reference to the name of a JavaScript file. You point the policy to a JavaScript file using the
ResourceURL element.

> [!WARNING]
> **Warning:** The Policy type must be capitalized appropriately in the Policy definition. Although "JavaScript" is the accepted spelling of the name of the programming language, in the Policy it must be capitalized as "Javascript".

For example, the following policy references the JavaScript file called
`setHeader.js`.

```javascript
<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>
```

> [!IMPORTANT]
> **Best practice:** Always use the extension `.js` for JavaScript resources.

> [!WARNING]
> **Warning:** The maximum time limit permitted for JavaScript policies to execute in environments in free trial organization is 200 milliseconds.

You can attach this policy to an API proxy flow as you would any other policy type. By
attaching the policy to the API proxy flow, you indicate where the JavaScript should be executed.
This enables you to execute JavaScript that interacts with request messages or response message
as those messages 'flow' through the API proxy. In this example, both JavaScripts execute in the
response flow, since the policies do two things: set HTTP headers on the response message and
'minimize' the response message that Apigee Edge returns to the requesting app.

If you open this flow configuration in the management UI, you will see the flow configuration
below.

Select **Proxy Endpoints \> default \> PostFlow** in the **Navigator
pane**.

![](https://docs.apigee.com/static/api-platform/images/javascript-cookbook-flow-ui.png)

The corresponding XML configuration for the ProxyEndpoint named 'default' is shown
below.

```javascript
<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>
```

Here's a summary of the flow's elements.

> [!NOTE]
> **Note:** This is a ProxyEndpoint flow. The ProxyEndpoint configuration defines the inbound (app-facing) interface for an API proxy. When you configure a ProxyEndpoint, you define how apps invoke the proxied API.

- **\<Request\>** - The \<Request\> element consists of several \<Step\> elements. Each step calls one of the policies that you create through the rest of this topic. These policies attach a JavaScript to the API proxy flow, and the location of the policy attachment determines when the JavaScript executes.
- **\<Response\>** - The \<Response\> element also includes \<Steps\>. These steps also call policies that are responsible for processing the final response from the target (which in this example is Apigee's mock service target--note the HTTPTargetConnection setting in under `/apiproxy/targets/default.xml`.)
- **\<HTTPProxyConnection\>** - Specifies the host and URI path that define the network address that apps call to consume this API.  
- **\<RouteRule\>** - This element specifies which TargetEndpoint configuration is invoked by the ProxyEndpoint.

## Adding JavaScript code to a proxy

JavaScript (like Python scripts, Java JAR files, XSLT files, and so on) are stored as
*resources*. When you are just starting to work with JavaScript it is easiest to store your
JavaScript files in the API proxy. As you advance, JavaScript should be made as generic and
reusable as possible, and then stored at the *environment* or *organization* level.
This prevents you from having to store the same JavaScript files in multiple API proxies, which
can quickly become unmanageable.

To learn about storing resources at the organization and environment level, see [Resource files](https://docs.apigee.com/api-platform/develop/resource-files).

Try it out

For instructions on deploying and calling the proxy, see the [JavaScript cookbook README](https://github.com/apigee/api-platform-samples/blob/master/doc-samples/javascript-cookbook/README.md).

### Importing and deploying
the API proxy

After you make changes, you can **Save** the API proxy in the API proxy builder
tool in [management UI](https://enterprise.apigee.com).

Or you can run the following command in the directory
`/api-platform-samples/doc-samples/javascript-cookbook`.

```javascript
$ sh deploy.sh
```

### Testing JavaScript

Run the following command in the directory
`/api-platform-samples/doc-samples/javascript-cookbook`.

```javascript
$ sh invoke.sh
```

The curl flag `-v` is used in the shell script to view HTTP headers on the response
message modified by the JavaScript.

You can directly submit a request as follows:

```javascript
$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook 
```

If the JavaScript executes properly, you will see a response like the following:

```javascript
< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}
```

You can now modify the JavaScript to try new things, redeploy the API proxy, and verify the
results by submitting the same request. Always make sure you deploy the API proxy that contains
your JavaScript to have your changes take effect.

## Script errors

You will inevitably see errors when writing JavaScript. The format of JavaScript errors that
you will see issued by an API proxy is shown below.

```javascript
{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}
```

## When to use JavaScript

On Apigee Edge, there is usually more than one way to implement specific functionality. Use
out-of-the-box policies where possible, and avoid the temptation to code all of your API proxy
logic in JavaScript. Even though Apigee Edge leverages compiled JavaScript to improve
performance, it is unlikely that JavaScript will perform as well as Policies. JavaScript may be
more difficult to maintain and debug. Reserve JavaScript for functionality that is unique to your
requirements.

If performance is a concern for custom functionality, use Java where possible.

## Summary

In this cookbook topic, you learned how JavaScript can be included in an API proxy
configuration to implement custom behavior. The custom behavior implemented by the samples
demonstrate how to get and variables, and how to parse JSON and construct custom response
messages.