# Parameters and Responses

Functions are blocks of code that run on demand without the need to manage any infrastructure. Develop on your local machine, test your code from the command line (using `doctl`), then deploy to a production namespace or App Platform — no servers required.

All Functions runtimes pass two parameters into their entrypoint – or *handler* – functions, and expect one return value. The details vary slightly from language to language, and you can read language-specific information for [Node.js](https://docs.digitalocean.com/products/functions/reference/runtimes/node-js/index.html.md), [Go](https://docs.digitalocean.com/products/functions/reference/runtimes/go/index.html.md), [Python](https://docs.digitalocean.com/products/functions/reference/runtimes/python/index.html.md), and [PHP](https://docs.digitalocean.com/products/functions/reference/runtimes/php/index.html.md).

This document covers the aspects of Functions parameters and responses that are the same for every language, including detailed information about the structure and contents of the [`event`](#event-parameter) and [`context`](#context-parameter) parameters, and the structure of the response your function should return.

## Overview

The *handler* of your function is the function that the runtime passes parameters to, and optionally receives a response dictionary from. By default, this is a function called `main`, but this can be set using the [`main` key in `project.yml`](https://docs.digitalocean.com/products/functions/reference/project-configuration/index.html.md#main).

The first parameter passed to the handler is `event`. This is the input event to the function, typically an HTTP request, or *web event*.

The second parameter, `context`, is data about the function’s execution environment, such as the time remaining before timeout, and memory allocations.

Both parameters are optional and you may ignore them if your function doesn’t require the information they provide.

## Event Parameter

The web event is always provided to the handler in the `event` parameter using whichever data type is most appropriate for the given language. In general, a dictionary-like data structure is used for all supported languages. For more specific details, see the language-specific **Event Parameter** sections for [Node.js](https://docs.digitalocean.com/products/functions/reference/runtimes/node-js/index.html.md#event-parameter), [Go](https://docs.digitalocean.com/products/functions/reference/runtimes/go/index.html.md#event-parameter), [Python](https://docs.digitalocean.com/products/functions/reference/runtimes/python/index.html.md#event-parameter), and [PHP](https://docs.digitalocean.com/products/functions/reference/runtimes/php/index.html.md#event-parameter).

The web event contains information about the HTTP request that initiated the function call. It usually contains HTTP headers and query string parameters, though the format can vary slightly depending on the value of the `web` key in the `project.yml` file (or the **Web Function** and **Raw HTTP** settings for functions deployed through the control panel interface):

- `web: true`: This is the default mode. Query string parameters and the request body are parsed and added as top-level keys in the `event` dictionary.
- `web: raw`: The HTTP request body and query string are included as-is instead of being parsed.
- `web: false`: No web event is included at all. The dictionary is empty unless you’ve [manually set parameters in the function’s `project.yml` file](https://docs.digitalocean.com/products/functions/reference/project-configuration/index.html.md#parameters) or passed them through a `doctl` command line invocation.

### Parsed Web Events

The default `web: true` event is structured like the following JSON example:

```js
{
  "http": {
    "headers": {
      "accept": String,
      "accept-encoding": String,
      "content-type": String,
      "user-agent": String,
      "x-forwarded-for": String,
      "x-forwarded-proto": String,
      "x-request-id": String
    },
    "method": String,
    "path": String
  },
  [String]: any
}
```

**Note**: Additional legacy keys such as `__ow_headers`, `__ow_method`, and `__ow_path` may be available in the event parameter. These keys are deprecated and should not be used. All of the data they contain is also provided under the `http` key, which should be used instead.

The `http` property contains details about the HTTP request:

- The `headers` of the request. The header names are all forced to lowercase and become keys of the `header` dictionary. Refer to the [HTTP Headers reference](https://docs.digitalocean.com/products/functions/reference/http-headers/index.html.md) for more information about the standard Functions HTTP headers
- The request’s HTTP `method` (`GET` or `POST` for example)
- The `path`, which is any additional information in the request URL after the function name, such as `/example/path`.

`[String]: any` refers to the parameters parsed from the body, query string, and `project.yml` configuration. They are placed at the top level of the event object and their keys are always strings. Their types depend on the type of the parameter provided: parameters parsed from the query string or a `x-www-form-urlencoded` body are always strings, but parameters parsed from a JSON body or `project.yml` retain their original type.

If the query string contains multiple instances of the same key, only the final value is present in the parsed event object. To avoid this behavior, use the `web: raw` option.

When parsed keys overlap between the query string, body, and [the `parameters:` field of `project.yml`](%28/products/functions/reference/project-configuration/#parameters%29) the following precedence applies:

```
body > query string > project.yml
```

Keys parsed from the request body override query string parameters, which override parameters set in the `project.yml` configuration file.

### Raw Web Events

For functions where `web: raw` is set, the query string and body are not parsed:

```js
{
  "http": {
    "body": String,
    "headers": {
      "accept": String,
      "accept-encoding": String,
      "content-type": String,
      "host": String,
      "user-agent": String,
      "x-forwarded-for": String,
      "x-forwarded-proto": String,
      "x-request-id": String
    },
    "isBase64Encoded": Boolean,
    "method": String,
    "path": String,
    "queryString": String
  }
  [String]: any
}
```

The raw web event differs from parsed web events in the following ways:

- The raw `body` and `queryString` are present
- `isBase64Encoded` is true when the input is binary. This allows for passing binary data to raw web functions
- `[String]: any` refers to any parameters you’ve set in `project.yml`. These are included at the top level of the dictionary. The keys are strings, and the values are whichever YAML type was originally used.

## Context Parameter

The `context` parameter contains information about the execution environment, such as memory allocations and the time remaining before a timeout.

Each language implements the `context` object slightly differently. For more specific details, see the language-specific **Context Parameter** sections for [Node.js](https://docs.digitalocean.com/products/functions/reference/runtimes/node-js/index.html.md#context-parameter), [Go](https://docs.digitalocean.com/products/functions/reference/runtimes/go/index.html.md#context-parameter), [Python](https://docs.digitalocean.com/products/functions/reference/runtimes/python/index.html.md#context-parameter), and [PHP](https://docs.digitalocean.com/products/functions/reference/runtimes/php/index.html.md#context-parameter).

Regardless of implementation details, the following information is present for all runtimes:

- **Activation ID**: The function’s activation ID. If the activation is asynchronous, you can use `doctl serverless activations get <your_activation_id>` to retrieve its full [activation record](https://docs.digitalocean.com/products/functions/reference/activation-records/index.html.md).
- **API host**: The API host URL
- **API key**: If enabled, the API authentication key that was used
- **Deadline**: A Unix timestamp in milliseconds indicating when the function’s invocation times out.
- **Function name**: The name of the function in the form `/<namespace_id>/<package_name>/<function_name>`.
- **Function version**: The version of the function. This is a [semantic version](https://semver.org/) that is automatically incremented each time the function is deployed
- **Namespace**: The name of the namespace the function was deployed into
- **Request ID**: An ID for the function invocation based on internal DigitalOcean monitoring systems.

The `context` parameter also contains a method that can be called by your function to get the time remaining before the invocation times out. The method name varies by runtime and is documented in the language-specific **Context Parameter** sections for [Node.js](https://docs.digitalocean.com/products/functions/reference/runtimes/node-js/index.html.md#context-parameter), [Go](https://docs.digitalocean.com/products/functions/reference/runtimes/go/index.html.md#context-parameter), [Python](https://docs.digitalocean.com/products/functions/reference/runtimes/python/index.html.md#context-parameter), and [PHP](https://docs.digitalocean.com/products/functions/reference/runtimes/php/index.html.md#context-parameter).

## Returns

Function responses are returned as a dictionary and each language has a slightly different implementation of this. Please see the language-specific **Returns** sections for [Node.js](https://docs.digitalocean.com/products/functions/reference/runtimes/node-js/index.html.md#returns), [Go](https://docs.digitalocean.com/products/functions/reference/runtimes/go/index.html.md#returns), [Python](https://docs.digitalocean.com/products/functions/reference/runtimes/python/index.html.md#returns), and [PHP](https://docs.digitalocean.com/products/functions/reference/runtimes/php/index.html.md#returns).

The returned dictionary can have three keys:

- `body`: The body of the response. Can be text or base64-encoded binary data. If `body` is a dictionary itself, it is converted to JSON and a `Content-Type: application/json` header is added to the response automatically.
- `statusCode`: The HTTP status code of the response. A `200` code is sent by default, or `204` if there is no `body` in the response.
- `headers`: A dictionary of additional headers to include in the response.

### JSON-only Responses

If you only ever want to return JSON data from your function, you can ignore the above requirements and instead return any result that can be serialized to JSON. To access this option, add `.json` to the end of your function URL when invoking it.

You may also use this `.json` URL format on functions that have a `body` and the other keys described in the previous section. Doing this allows you to see the whole raw response object as JSON, which can be useful when debugging function responses.