Scripting API

relay.sendRequest

A function that sends another request from a script and passes back its response.

Declaration

relay.sendRequest(request: string | object, callback?: (error: Error | null, response: Response | null) => void): Promise<Response> | undefined

Overview

Use relay.sendRequest to call another endpoint from a script, such as to get a token before the request is sent. Without a callback, it returns a promise you can await. With a callback, it returns nothing and calls the callback when the response arrives.

const response = await relay.sendRequest({
  url: relay.variables.replaceIn("{{baseUrl}}/oauth/token"),
  method: "POST",
  header: { "Content-Type": "application/json" },
  body: {
    mode: "raw",
    raw: JSON.stringify({
      client_id: relay.environment.get("clientId"),
      client_secret: relay.environment.get("clientSecret")
    })
  }
});
relay.environment.set("token", response.json().access_token);

Parameters

Prop

Type

A request object can have these properties:

Prop

Type

A body object has a mode and the property of the same name:

ModePropertyExample
"raw"raw: the body's text. Add options: { raw: { language: "json" } }, or a Content-Type: application/json header, to send it as JSON.{ mode: "raw", raw: "{\"a\":1}", options: { raw: { language: "json" } } }
"urlencoded"urlencoded: a list of { key, value } objects, or an object of names and values.{ mode: "urlencoded", urlencoded: [{ key: "grant_type", value: "client_credentials" }] }
"formdata"formdata: a list of { key, value } objects.{ mode: "formdata", formdata: [{ key: "name", value: "Ada" }] }
"graphql"graphql: an object with a query and optional variables and operationName.{ mode: "graphql", graphql: { query: "{ me { id } }" } }

To send the request's own body, pass body: relay.request.body.

Return Value

A promise that resolves to the response, or undefined when you pass a callback. The response has the same members as relay.response, including json() and to assertions.

Discussion

What's sent

Relay sends the request exactly as you describe it:

  • {{name}} tokens aren't resolved. Expand them first with relay.variables.replaceIn().
  • The authentication of the request, its folders, collection and workspace isn't applied. Add the Authorization header yourself.
  • A body on a GET, HEAD or TRACE request isn't sent.

The request uses the settings of the request whose script sent it, such as its timeout, redirects, proxy and certificates. It sends the cookies in the workspace's cookie jar, and cookies the response sets are added to the jar, unless cookies are turned off for the workspace.

The request doesn't appear in history.

Errors

The callback gets an error, or the promise rejects, only when there's no response, such as when the host can't be found or the request times out. A response with a status such as 404 or 500 isn't an error; check response.code.

Limits

A script isn't finished until every request it sent has a response, even when it doesn't await them, and the time they take counts toward the Script Timeout setting. A script can send at most 50 requests in each phase.

See Also