relay.request
The request being sent, which pre-request scripts can change.
Declaration
relay.request: RequestOverview
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: stringThe request's id.
name
relay.request.name: stringThe request's name.
Method and URL
method
relay.request.method: stringThe 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: UrlThe 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: PropertyListThe request's headers, matched without regard to case. See PropertyList.
addHeader(header)
relay.request.addHeader(header: { key: string, value: string } | string): voidAdds a header, keeping any others with the same name. Pre-request scripts only.
upsertHeader(header)
relay.request.upsertHeader(header: { key: string, value: string }): voidSets a header, replacing one with the same name. Pre-request scripts only.
removeHeader(key)
relay.request.removeHeader(key: string): voidRemoves every header named key. Pre-request scripts only.
getHeaders(options)
relay.request.getHeaders(options?: { ignoreCase?: boolean }): objectReturns 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[]): voidAdds 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[]): voidRemoves the query parameters with the given names. Pre-request scripts only.
Body
body
relay.request.body: RequestBodyThe request's body. See Request body.
Serialization
toJSON()
relay.request.toJSON(): objectReturns the request as a plain object with its id, name, method, url, header and body.
Unsupported members
auth
relay.request.authReading 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(): stringReturns the full URL as a string, including its query parameters. getRaw() and the raw property return the same string.
getHost()
url.getHost(): stringReturns the host, such as "api.example.com".
getRemote()
url.getRemote(): stringReturns the host, with the port when there is one.
getPath()
url.getPath(): stringReturns the path, starting with a slash.
getQueryString()
url.getQueryString(): stringReturns the query string, without the leading question mark.
getPathWithQuery()
url.getPathWithQuery(): stringReturns the path followed by the query string.
URL parts
protocol
url.protocol: string | undefinedThe scheme, such as "https".
host
url.host: string[]The host, as a list of its labels.
port
url.port: string | undefinedThe port, or undefined when the URL has none.
path
url.path: string[]The path, as a list of its segments.
hash
url.hash: string | undefinedThe fragment after the #, if any.
query
url.query: PropertyListThe URL's query parameters. See PropertyList.
Changing the URL
update(url)
url.update(url: string): voidReplaces the whole URL, including its query parameters.
addQueryParams(params)
url.addQueryParams(params: string | object | object[]): voidAdds query parameters, from a string or a list of { key, value } objects.
removeQueryParams(keys)
url.removeQueryParams(keys: string | string[]): voidRemoves 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" | undefinedThe kind of body, or undefined when the request has none. Assigning a mode changes the body's kind.
raw
body.raw: string | undefinedThe body's text, for a raw body. Assigning text makes the body a raw body with that text.
urlencoded
body.urlencoded: PropertyListThe fields of a URL-encoded form body.
formdata
body.formdata: PropertyListThe fields of a multipart form body.
graphql
body.graphql: { query: string, variables: string, operationName?: string } | undefinedThe query, the variables as JSON text, and the operation name of a GraphQL body.
options
body.options: objectExtra settings for the body, such as { raw: { language: "json" } } for a JSON body.
isEmpty()
body.isEmpty(): booleanReturns whether the body has no content.
toString()
body.toString(): stringReturns a raw body's text, or a URL-encoded body as a query string.
Changing the body
update(options)
body.update(options: string | object): voidReplaces 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
- PropertyList: The list of keys and values behind headers, query parameters, form fields and cookies.
- relay.response: The response a post-response script checks, with its status, headers and body.
- Running scripts before and after requests: Add pre-request and post-response scripts to requests, folders and collections.