Feeds are composed of items, but in API Script items themselves are used for much more than the individual parts of a feed. They are also used to represent inputs to operations.

Declare Items

In API Script items are created, named, and given attribute values through the api:set keyword:

<api:set item="input" attr="mask" value="*.txt" />

The line above sets the “mask” attribute to the value “*.txt” on the item named “input”. In this case, the input item is like a variable in API Script. However, an item named “input” is never declared. Instead, the item is created the first time you try to set an attribute on it. In the example above, if the input item did not already exist, it would be created and the mask attribute would be set on it.

Select Attribute Values

To reference an attribute, use the syntax item.attribute (e.g., “input.mask”). To query an attribute value, surround the attribute name in square brackets ([]). This instructs the interpreter that you want to evaluate the string instead of interpreting it as a string literal.

For example, consider the following code snippet:

<api:set item="item1" attr="attr1" value="value1"/>
<api:set item="item1" attr="attr2" value="item1.attr1"/>
<api:set item="item1" attr="attr3" value="[item1.attr1]"/>

The results are the following:

• item1.attr1 gets assigned the literal string value “value1”.
• item1.attr2 gets assigned the literal string value “item1.attr1”.
• item1.attr3 gets assigned the value “value1”, because the string “[item1.attr1]” gets evaluated at run time as the attr1 attribute of item1.

Note that you can use a backslash to escape square brackets in string literals.

Default Item

In API Script there is always an implicit, unnamed item on an internal stack of items, the default item. In the following two cases, the default item is commonly used to make scripts shorter and easier to write:

• Calling operations: The default item is the item passed by default to the operation called by your script if no other item is specified. This means that you can use api:set to write attributes to the default unnamed item and those attributes will be passed as input to the next operation called in the script. This is one way to provide an operation’s required parameters.
• Processing the current item in the output of an operation or script: If you do not specify a variable name for the result of an operation, then inside the api:call block that invokes the operation, the default item will refer to the current item produced by the operation.

Manipulate the default item by simply omitting the item attribute of an API Script keyword:

<api:set attr="path" value="." />

Special Items

In addition to items declared within the script, several built-in items are available in the scope of a script. Built-in, or special, items are available in API Script that provide an interface for accessing parts of HTTP requests, responses, and more. These special items are useful for mapping inputs in HTTP requests to operation inputs.

The following sections detail the special items.

Script Inputs (_input)

The input for a script can be read from the _input item. The _input item contains variables found in the URL query string and the POST data when the script is executed. If a variable of the same name exists in the POST data, it overrides the value from the query string.

When you read values from the default item in a script, you are reading values from _input; likewise, attributes that you write to the default item are passed as parameters to operations along with the input to the script. Only the variables defined in the info block or in the script will be available in the _input item.

Note that inside an api:call block _input is no longer the default item and you must reference it by name if you need access to it.

Script Outputs (_out[n])

The current item in the feed produced by the api:call keyword can be accessed through the default item or a named special item, “_outX”, where X is the level of nesting of api:call keywords. For example, if you are inside a single api:call keyword, the item’s name will be “_out1”. If you are inside three levels of nested api:call keywords, then it will be _out3.

HTTP Request (_request)

You can access variables passed into the URL query string, POSTed to the script, and other variables as collections of attributes in the _request item. To access a specific collection of attributes, use the name of the collection as the prefix to the attribute you want to read. For example, [_request.qstring:name] reads the value of the variable “name” in the query string and [_request.form:name] reads the value of the variable “name” in the form data.

• [query]string:* Access the values of query string parameters.
• form:* Access the values of variables in the form data.
• server:* Access the values of server variables.
• body:* Access the raw contents (body) of the request.
• auth:* Access authentication information about the user. Determine whether the user is authenticated with [_request.auth:isauthenticated].
• other:* Access other information about the request. Retrieve the application path with [_request.other:applicationpath].

HTTP Response (_response)

The response item allows the script writer to write directly to the HTTP response. You can set the attributes listed below in the response item.

• cookie:* Set cookies in the response. The name of the attribute is the name of the cookie prefixed by “cookie:” and the value of the attribute is the cookie value.
• writefile Write the content of the specified path to the response.
• redirect Send the redirect header to the client browser. This can be used to redirect the browser to another URL.
• statuscode Set the HTTP status code of the response.
• statusdescription Set the HTTP status description of the response.

HTTP Headers (_httpheaders)

The _httpheaders item provides easy access to HTTP headers in scripts and templates. You can read the HTTP request headers by reading from this item. Write to the outgoing response headers by writing to this item. For example, you can set the content type with a line like the following:

<api:set item="_httpheaders" attr="content-type" value="application/xml"/>

HTTP Cookies (_cookies)

You can use the _cookies item to retrieve cookies in the request and set cookies in the response. A cookie with multiple key/value pairs is represented as a collection of attributes that correspond to the key/value pairs of the cookie. The name of the cookie prefixes each attribute of the collection.

ASP.NET Session (_session)

ASP.NET session variables are available in API Script through the _session item. Any object stored in the session can be accessed as attributes of this item. The attribute name represents the key used to store the object in the session.