Supported formats
The import formats, body types, auth types and limits Relay supports.
Overview
This page lists what Relay can import, send and export, and the limits it applies. For how to use each feature, follow the links in each section.
Import formats
| Format | Versions | What Relay creates |
|---|---|---|
| OpenAPI | 3.0 and 3.1, in JSON or YAML | A collection with a folder per tag, a baseUrl variable, empty credential variables and the spec's auth. |
| Postman collection | v2.0 and v2.1, in JSON | A collection with its nested folders, variables, auth, scripts and request settings. |
| Postman environment | JSON export | An environment in an existing workspace. Variables of the secret type stay secret. |
| cURL command | Any command starting with curl | A draft request. A ws:// or wss:// URL creates a WebSocket request. |
You can import from a file, from pasted text, or, for OpenAPI and Postman, from a URL. Documents can be up to 20 MB.
From an OpenAPI spec, Relay maps these security schemes onto Relay auth: HTTP bearer, basic and digest, API keys in a header or query parameter, OAuth 2.0 with the authorization code or client credentials flow, and OpenID Connect, which becomes OAuth 2.0 without its endpoints. API keys sent as cookies go in a Cookie header.
From a Postman collection, Relay maps the followRedirects, maxRedirects, strictSSL, followOriginalHttpMethod and followAuthorizationHeader settings onto request settings at every level and keeps {{$name}} dynamic variables as written.
The cURL importer reads these options: --url, -X/--request, -I/--head, -G/--get, -H/--header, -A/--user-agent, -e/--referer, -b/--cookie, -d/--data, --data-ascii, --data-raw, --data-binary, --data-urlencode, --json, --url-query, -F/--form, --form-string, -u/--user, --basic, --digest, --ntlm, --aws-sigv4, --oauth2-bearer, -L/--location, --location-trusted, --max-redirs, --post301, --post302, --post303, -k/--insecure and -m/--max-time. It ignores options that only control how curl runs, such as -s and -v, and reports each one.
For details, see Importing OpenAPI specs, Importing Postman collections and environments and Importing cURL commands.
HTTP methods
Relay offers GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS, and accepts any other method name that's a valid HTTP token, such as PROPFIND, PURGE or QUERY, up to 32 characters. Method names are uppercased. CONNECT isn't supported.
GET, HEAD and TRACE requests can't have a body. Every other method can.
Body types
| Body | Sent as |
|---|---|
| None | No body. |
| Text | The text, with the content type you choose. |
| JSON | JSON text, with Content-Type: application/json. |
| GraphQL | A JSON POST of the query, operation name and variables. |
| Form URL-Encoded | Fields encoded as application/x-www-form-urlencoded. |
| Multipart Form | Text fields and files as multipart/form-data. |
For details, see Adding a request body and Sending GraphQL queries.
Auth types
| Auth | Variants |
|---|---|
| Bearer Token | — |
| Basic Auth | — |
| API Key | Sent in a header or a query parameter. |
| OAuth 2.0 | Authorization Code and Client Credentials grants. |
| OAuth 1.0 | HMAC-SHA1, HMAC-SHA256, HMAC-SHA512, RSA-SHA1, RSA-SHA256, RSA-SHA512 and PLAINTEXT signatures. |
| JWT Bearer | HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 and ES512. |
| Digest Auth | — |
| NTLM | — |
| AWS Signature | Signature Version 4. |
| Hawk | — |
Any request, folder, collection or workspace can also inherit auth from the level above or turn it off with No Auth. For details, see Inheriting authentication.
Streaming and WebSockets
A response with the content type text/event-stream is shown as a server-sent event stream as it arrives, whatever its method, body and auth.
WebSocket requests connect to ws:// and wss:// URLs, with subprotocols, an optional ping interval and a maximum message size. Saved messages can be text, JSON or binary. The opening handshake uses the request's auth, except Digest Auth, which WebSocket requests don't support.
For details, see Receiving server-sent events and Connecting to a WebSocket server.
Code export
| Kind | Generators |
|---|---|
| HTTP | Raw; Shell: cURL, HTTPie, Wget; PowerShell: Invoke-RestMethod; JavaScript: Fetch API, Axios, XMLHttpRequest; Python: Requests, http.client; Go: net/http; Java: HttpClient, OkHttp; Kotlin: OkHttp; C#: HttpClient, RestSharp; PHP: cURL, Guzzle; Ruby: Net::HTTP; Swift: URLSession; Rust: reqwest; C: libcurl |
| WebSocket | Raw; Shell: websocat; JavaScript: WebSocket (browser), ws; Python: websockets; Go: gorilla/websocket; Java: OkHttp; Kotlin: OkHttp; C#: ClientWebSocket; Swift: URLSessionWebSocketTask |
You can add your own generators in JavaScript. For details, see Generating code from requests.
Limits
| Limit | Value |
|---|---|
| Request timeout | 1 to 3600 seconds. Default 30. |
| Streaming idle timeout | 1 to 86,400 seconds. Default 300. |
| Script timeout, per phase | 1 to 300 seconds. Default 30. |
| Maximum redirects | 1 to 50. Default 10. |
| History entries | 10 to 500. Default 100. |
| Import document size | 20 MB. |
| Syntax highlighting | Text up to 128 KB. Larger text is shown plain. |
| Pretty HTML formatting | Bodies up to 8 MB and 256 levels deep. Larger or deeper HTML is shown as received. |
| WebSocket message size | 16 MB by default, set for each request. |
| Raw body of an event stream | The first 64 MB. Later events are still shown. |
| Events or messages shown while a stream or connection is open | The latest 10,000, up to 64 MB. |
| Events or messages saved in history | The latest 2,000, up to 8 MB. |
| Response body readable by scripts | 50 MB. |
| Custom method names | 32 characters. |
Not supported
- Swagger 2.0 specs: Convert the spec to OpenAPI 3 first.
- Postman Collection v1, Postman globals and Postman data exports: Export a single collection as v2.1 instead, and add globals as global variables in Relay.
- Some Postman features: File fields in form bodies and Akamai EdgeGrid and ASAP auth are left out with a warning. Saved OAuth 2.0 tokens aren't imported.
- OAuth 2.0 implicit and password grants.
- GraphQL over GET and GraphQL subscriptions.
- socket.io: Relay connects to plain WebSocket servers.
- CONNECT requests.
- Digest Auth on WebSocket connections.
See Also
- Importing OpenAPI specs: Create a collection of requests from an OpenAPI 3.0 or 3.1 spec.
- Importing Postman collections and environments: Bring Postman collections, with their folders, auth and scripts, and Postman environments into Relay.
- Keyboard shortcuts: The keyboard shortcuts for Relay's commands.