Scripting API

relay.request

The request being sent, which pre-request scripts can change.

Declaration

relay.request: Request

Overview

In a pre-request script, relay.request is the request as you wrote it in the request editor: its {{name}} tokens aren't resolved yet, and headers that its authentication adds aren't there. Changes a script makes apply to this send only. The request in the editor, and the copy Relay keeps in history, stay as you wrote them.

// Sign the request with an HMAC of its method and path.
const secret = relay.environment.get("signingSecret") ?? "";
const payload = relay.request.method + "\n" + relay.request.url.getPathWithQuery();
const signature = CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Base64);
relay.request.headers.upsert({ key: "X-Signature", value: signature });

In a post-response script, relay.request is the request that was sent, with its variables resolved, and it's read-only. A change throws an error that says the request can only be changed in a pre-request script.

Topics

Identity

id

relay.request.id: string

The request's id.

name

relay.request.name: string

The request's name.

Method and URL

method

relay.request.method: string

The request's HTTP method, such as "GET". Assigning a method changes it for this send; Relay uppercases it, and a send with an invalid method fails.

url

relay.request.url: Url

The request's URL, with its parts and query parameters. Assigning a string replaces the whole URL, as url.update() does.

Headers

headers

relay.request.headers: PropertyList

The request's headers, matched without regard to case. See PropertyList.

addHeader(header)

relay.request.addHeader(header: { key: string, value: string } | string): void

Adds a header, keeping any others with the same name. Pre-request scripts only.

upsertHeader(header)

relay.request.upsertHeader(header: { key: string, value: string }): void

Sets a header, replacing one with the same name. Pre-request scripts only.

removeHeader(key)

relay.request.removeHeader(key: string): void

Removes every header named key. Pre-request scripts only.

getHeaders(options)

relay.request.getHeaders(options?: { ignoreCase?: boolean }): object

Returns the enabled headers as an object of names and values. With ignoreCase: true, the names are lowercased.

Query parameters

addQueryParams(params)

relay.request.addQueryParams(params: string | object | object[]): void

Adds query parameters, from a string such as "page=2&limit=50" or from { key, value } objects. Pre-request scripts only.

removeQueryParams(keys)

relay.request.removeQueryParams(keys: string | string[]): void

Removes the query parameters with the given names. Pre-request scripts only.

Body

body

relay.request.body: RequestBody

The request's body. See Request body.

Serialization

toJSON()

relay.request.toJSON(): object

Returns the request as a plain object with its id, name, method, url, header and body.

Unsupported members

auth

relay.request.auth

Reading it throws an error. Set authentication in the request's Auth tab, or add an Authorization header.

URL

relay.request.url is an object with these members. Write methods are for pre-request scripts only.

Reading the URL

toString()

url.toString(): string

Returns the full URL as a string, including its query parameters. getRaw() and the raw property return the same string.

getHost()

url.getHost(): string

Returns the host, such as "api.example.com".

getRemote()

url.getRemote(): string

Returns the host, with the port when there is one.

getPath()

url.getPath(): string

Returns the path, starting with a slash.

getQueryString()

url.getQueryString(): string

Returns the query string, without the leading question mark.

getPathWithQuery()

url.getPathWithQuery(): string

Returns the path followed by the query string.

URL parts

protocol

url.protocol: string | undefined

The scheme, such as "https".

host

url.host: string[]

The host, as a list of its labels.

port

url.port: string | undefined

The port, or undefined when the URL has none.

path

url.path: string[]

The path, as a list of its segments.

hash

url.hash: string | undefined

The fragment after the #, if any.

query

url.query: PropertyList

The URL's query parameters. See PropertyList.

Changing the URL

update(url)

url.update(url: string): void

Replaces the whole URL, including its query parameters.

addQueryParams(params)

url.addQueryParams(params: string | object | object[]): void

Adds query parameters, from a string or a list of { key, value } objects.

removeQueryParams(keys)

url.removeQueryParams(keys: string | string[]): void

Removes the query parameters with the given names.

Request body

relay.request.body is an object with these members. Write methods are for pre-request scripts only.

A JSON body has the mode "raw" and the language "json". A GraphQL body has the mode "graphql".

Reading the body

mode

body.mode: "raw" | "urlencoded" | "formdata" | "graphql" | undefined

The kind of body, or undefined when the request has none. Assigning a mode changes the body's kind.

raw

body.raw: string | undefined

The body's text, for a raw body. Assigning text makes the body a raw body with that text.

urlencoded

body.urlencoded: PropertyList

The fields of a URL-encoded form body.

formdata

body.formdata: PropertyList

The fields of a multipart form body.

graphql

body.graphql: { query: string, variables: string, operationName?: string } | undefined

The query, the variables as JSON text, and the operation name of a GraphQL body.

options

body.options: object

Extra settings for the body, such as { raw: { language: "json" } } for a JSON body.

isEmpty()

body.isEmpty(): boolean

Returns whether the body has no content.

toString()

body.toString(): string

Returns a raw body's text, or a URL-encoded body as a query string.

Changing the body

update(options)

body.update(options: string | object): void

Replaces the body, such as with { mode: "raw", raw: text }.

relay.request.body.update({
  mode: "raw",
  raw: JSON.stringify({ name: "Ada", sentAt: Date.now() }),
  options: { raw: { language: "json" } }
});

A string replaces the text of a raw body, or makes the body raw text. For a form, pass { mode: "urlencoded", urlencoded: [{ key, value }] } or { mode: "formdata", formdata: [{ key, value }] }, and for GraphQL pass { mode: "graphql", graphql: { query, variables } }, where variables can be an object.

Discussion

When a pre-request script gives a GET, HEAD or TRACE request a body, Relay doesn't send the body and writes a warning to the Console. Changes to relay.request don't affect the request's authentication, which Relay applies after the scripts run.

See Also