REST connection

rest

A REST connection is a connection to a REST api that can be reused from transforms like the REST client.

The REST connection is a generic purpose metadata item.

When a REST client transform selects a REST connection, the connection supplies the whole client: proxy, authentication, SSL/TLS and timeouts. The transform’s own fields for those settings are no longer read, and the transform dialog greys them out.

Their values are kept, so clearing the connection brings them back, and init() logs which of them it ignored. What the transform still contributes per request is the path, the HTTP method, headers, query and matrix parameters, and the body.

Related Plugins

REST client

Options

Option	Description
Name	The name to be used for this REST connection
Base URL	The URL to use as the base URL for any API calls. The base URL will need to be appended from client transforms or actions that use it to make detailed API calls.
Test URL	A full URL that can be used to test this REST connection. If no test URL is specified, the base URL will be used to perform connection tests.
Authentication type	Select how Hop should authenticate when this metadata is used. The available choices are described below.

Option

Description

Name

The name to be used for this REST connection

Base URL

The URL to use as the base URL for any API calls. The base URL will need to be appended from client transforms or actions that use it to make detailed API calls.

Test URL

A full URL that can be used to test this REST connection. If no test URL is specified, the base URL will be used to perform connection tests.

Authentication type

Select how Hop should authenticate when this metadata is used. The available choices are described below.

Use environment variables or Hop variables (for example ${PROJECT_HOME}) in any text box. The connection resolves variables when the metadata is loaded, so the same definition can be reused from pipelines, workflows, and the Hop GUI test button.

Authentication

Type Fields Description

Type	Fields	Description
No Auth	—	No authentication headers are generated. Useful for public endpoints or when a downstream transform sets headers manually.
API Key	Authorization header name, Authorization prefix (optional), Authorization value	Adds a header such as `Authorization: Bearer <token>` or any other custom header. Prefix is concatenated with the value when present.
Basic	Username, Password, Preemptive	Sends HTTP Basic credentials. Passwords can be stored encrypted. See Preemptive authentication below.
Bearer	Bearer token	Adds an `Authorization: Bearer <token>` header automatically.
OAuth 2	Token URL, Grant type, Client ID, Client secret, Refresh token, Scope	Fetches an access token from the token endpoint and sends it as a Bearer header. See OAuth 2 below.

No Auth

—

No authentication headers are generated. Useful for public endpoints or when a downstream transform sets headers manually.

API Key

Authorization header name, Authorization prefix (optional), Authorization value

Adds a header such as Authorization: Bearer <token> or any other custom header. Prefix is concatenated with the value when present.

Basic

Username, Password, Preemptive

Sends HTTP Basic credentials. Passwords can be stored encrypted. See Preemptive authentication below.

Bearer

Bearer token

Adds an Authorization: Bearer <token> header automatically.

OAuth 2

Token URL, Grant type, Client ID, Client secret, Refresh token, Scope

Fetches an access token from the token endpoint and sends it as a Bearer header. See OAuth 2 below.

Mutual TLS (mTLS) is not an authentication type. A client certificate is presented during the TLS handshake rather than in the Authorization header, so it is configured in SSL and client certificates below and can be combined with any of the types above.

Preemptive authentication

With Preemptive selected (the default), Basic credentials are sent on the first request. With it cleared, Hop sends the request without credentials, waits for a 401 challenge, and then repeats the request with the Authorization header.

Preemptive is the right choice for almost every API, and it is what Hop has always done. Clear it only for a server that requires the challenge round trip. Note that an API answering an unauthenticated request with anything other than 401 — a 403, or a 200 carrying an error body — will never receive the credentials at all.

SSL and client certificates

Option Description

Option	Description
Trust store file	Path to a trust store (JKS or PKCS12) that contains server CA certificates. Leave empty to use the JVM default trust store. When `Ignore SSL errors` is enabled Hop installs a trust-all manager instead.
Trust store password	Password for the trust store file. Supports variable substitution and encrypted values.
Ignore SSL errors	If selected, Hop trusts all certificates and skips hostname verification. This should only be used in development or test environments.
Key store file	Path to the client key store used for certificate authentication. PKCS12 (`.p12`, `.pfx`) and JKS files are supported.
Key store password	Password for the key store.
Key store type	Explicitly choose `PKCS12` or `JKS`. Defaults to PKCS12 when not specified.
Key password	Optional password that protects a private key entry inside the key store. Falls back to the key store password when left empty.
Certificate alias	Optional alias to pick a specific certificate inside the key store. Leave empty to use the default entry.

Trust store file

Path to a trust store (JKS or PKCS12) that contains server CA certificates. Leave empty to use the JVM default trust store. When Ignore SSL errors is enabled Hop installs a trust-all manager instead.

Trust store password

Password for the trust store file. Supports variable substitution and encrypted values.

Ignore SSL errors

If selected, Hop trusts all certificates and skips hostname verification. This should only be used in development or test environments.

Key store file

Path to the client key store used for certificate authentication. PKCS12 (.p12, .pfx) and JKS files are supported.

Key store password

Password for the key store.

Key store type

Explicitly choose PKCS12 or JKS. Defaults to PKCS12 when not specified.

Key password

Optional password that protects a private key entry inside the key store. Falls back to the key store password when left empty.

Certificate alias

Optional alias to pick a specific certificate inside the key store. Leave empty to use the default entry.

Use the Test button to validate the selected authentication method and SSL settings against the test or base URL. The dialog resolves variables before running the test so it matches pipeline execution.

OAuth 2

Hop obtains the access token itself, so an OAuth-protected API needs no scripting to sign or refresh anything.

Option Description

Option	Description
Token URL	The token endpoint, for example `https://login.example.com/oauth2/token`.
Grant type	`CLIENT_CREDENTIALS` for machine-to-machine access, where the client ID and secret are the credentials. `REFRESH_TOKEN` to exchange a long-lived refresh token, obtained once interactively, for access tokens.
Client ID / Client secret	The registered client credentials. The secret is stored encrypted.
Refresh token	Only for the `REFRESH_TOKEN` grant. Stored encrypted.
Scope	Optional, space separated.
Send credentials in body	Controls where the client secret travels. By default it goes in a Basic `Authorization` header, which RFC 6749 §2.3.1 requires every server to accept; tick this for a server that only accepts it in the form body. The client ID is always sent in the body as well, whichever setting you choose — RFC 6749 §4.1.3 lists it as a body parameter and Microsoft Entra ID rejects a request without it (`AADSTS900144`) even when the header carries the same value.

Token URL

The token endpoint, for example https://login.example.com/oauth2/token.

Grant type

CLIENT_CREDENTIALS for machine-to-machine access, where the client ID and secret are the credentials. REFRESH_TOKEN to exchange a long-lived refresh token, obtained once interactively, for access tokens.

Client ID / Client secret

The registered client credentials. The secret is stored encrypted.

Refresh token

Only for the REFRESH_TOKEN grant. Stored encrypted.

Scope

Optional, space separated.

Send credentials in body

Controls where the client secret travels. By default it goes in a Basic Authorization header, which RFC 6749 §2.3.1 requires every server to accept; tick this for a server that only accepts it in the form body. The client ID is always sent in the body as well, whichever setting you choose — RFC 6749 §4.1.3 lists it as a body parameter and Microsoft Entra ID rejects a request without it (AADSTS900144) even when the header carries the same value.

Option	Description
Authorization URL	The authorization endpoint, used only by Authorize below. A pipeline never visits it.
Redirect URI	Where the authorization server sends the browser back. It must match one registered with the provider.
Authorize…	Runs the consent flow once, at design time. See below.

Option

Description

Authorization URL

The authorization endpoint, used only by Authorize below. A pipeline never visits it.

Redirect URI

Where the authorization server sends the browser back. It must match one registered with the provider.

Authorize…

Runs the consent flow once, at design time. See below.

Authorize

CLIENT_CREDENTIALS needs no human. When the API instead requires a user to consent, click Authorize…:

Hop builds an authorization URL with PKCE (RFC 7636) and shows it. Open in browser launches it.
Approve the request. The browser lands on your redirect URI with a code= parameter in the address bar.
Copy that code and paste it back into the dialog.

Hop exchanges the code for tokens, fills in the Refresh token field and switches the grant to REFRESH_TOKEN. Save the connection, and pipelines run unattended from then on — the browser step happens once, not per run.

The exchange goes through the connection’s proxy and TLS settings like every other request, so authorizing from behind a corporate proxy works.

If the provider returns no refresh token, Hop reports it rather than appearing to succeed — a connection that silently kept only an access token would work until it expired and then need a human again. Providers need to be asked for offline access explicitly: put offline_access in Scope, alongside the scopes for the API itself. On Microsoft Entra ID that means, for example, offline_access api://your-app/Default_scope. The error message shows the scope the server actually granted, which is the quickest way to see that it is missing.

A code is pasted rather than captured by a local listener: Hop cannot assume it may bind a port, and most providers only accept redirect URIs registered with them in advance.

Tokens are cached and shared. A transform running several copies would otherwise request a token per copy, and token endpoints are commonly rate-limited — some providers also invalidate the previous token whenever they issue one, so the copies would knock each other offline. The cache is keyed on the token URL, client ID, grant and scope, so connections that share those share a token.

Hop refreshes 30 seconds before the expires_in the server reported, to absorb clock skew; if the server reports no expiry, the token is treated as lasting five minutes.

The token request goes out through the same client as the API call, so it uses the connection’s proxy, TLS settings and timeouts.

Advanced

The Advanced tab holds the timeouts and the proxy the connection uses.

Option Description

Option	Description
Connect timeout (ms)	How long to wait for the connection to be established. Leave empty for no timeout.
Read timeout (ms)	How long to wait for response data. Leave empty for no timeout.
Proxy scheme	`http` or `https`. Defaults to `http`. Use `https` when the proxy itself is reached over TLS.
Proxy host	Host name of the proxy. Leave empty to connect directly.
Proxy port	Port of the proxy. Defaults to `8080` for `http` and `443` for `https`.
Proxy username	Username for a proxy that requires authentication. Leave empty for an open proxy.
Proxy password	Password for the proxy user. Supports encrypted values.
Bypass proxy for	Hosts to reach directly instead of through the proxy, in JDK `http.nonProxyHosts` syntax: entries separated by `\|`, `,` or `;`, each optionally using `` as a wildcard (for example `localhost\|.internal.example.com`).

Connect timeout (ms)

How long to wait for the connection to be established. Leave empty for no timeout.

Read timeout (ms)

How long to wait for response data. Leave empty for no timeout.

Proxy scheme

http or https. Defaults to http. Use https when the proxy itself is reached over TLS.

Proxy host

Host name of the proxy. Leave empty to connect directly.

Proxy port

Port of the proxy. Defaults to 8080 for http and 443 for https.

Proxy username

Username for a proxy that requires authentication. Leave empty for an open proxy.

Proxy password

Password for the proxy user. Supports encrypted values.

Bypass proxy for

Hosts to reach directly instead of through the proxy, in JDK http.nonProxyHosts syntax: entries separated by |, , or ;, each optionally using * as a wildcard (for example localhost|*.internal.example.com).

The bypass list is evaluated for every request, so it still works on a REST client transform whose target host changes from row to row.

Pagination

The Pagination tab defines how the REST client transform advances through paged API responses when pagination is enabled on the transform.

Pagination is configured on the connection; the REST client reads these settings and performs the HTTP loop. When the connection pagination strategy is NONE, the REST client performs a single request per incoming row (legacy behaviour).

Option Description

Option	Description
Pagination strategy	How Hop obtains the next page. See the strategies below. Default is `NONE`.
Page / cursor parameter name	Query parameter name for `PAGE_NUMBER` or `CURSOR` (for example `page`, `cursor`), body field name for `BODY_CURSOR`, or request header name for `HEADER_CURSOR`. Ignored by `OFFSET_LIMIT`, `LINK_HEADER` and `BODY_NEXT_URL`.
Offset query parameter name	Query parameter for the starting index in `OFFSET_LIMIT` paging. Defaults to `offset` when blank.
Limit / batch size parameter name	Parameter for the batch size, used by `OFFSET_LIMIT`, `BODY_CURSOR` and `HEADER_CURSOR`. Defaults to `limit` when blank.
Default batch size	Page size sent with `OFFSET_LIMIT`, `BODY_CURSOR` and `HEADER_CURSOR`. When `0`, Hop falls back to an internal default (100).
Cursor JsonPath	JsonPath expression against a JSON response body to read the next cursor token, for every cursor strategy.
Cursor XPath	XPath expression against an XML response body to read the next cursor token, for every cursor strategy.
Next page URL JsonPath	JsonPath expression that reads the next page URL out of a JSON response body (`BODY_NEXT_URL`).
Next page URL XPath	XPath expression that reads the next page URL out of an XML response body (`BODY_NEXT_URL`).

Pagination strategy

How Hop obtains the next page. See the strategies below. Default is NONE.

Page / cursor parameter name

Query parameter name for PAGE_NUMBER or CURSOR (for example page, cursor), body field name for BODY_CURSOR, or request header name for HEADER_CURSOR. Ignored by OFFSET_LIMIT, LINK_HEADER and BODY_NEXT_URL.

Offset query parameter name

Query parameter for the starting index in OFFSET_LIMIT paging. Defaults to offset when blank.

Limit / batch size parameter name

Parameter for the batch size, used by OFFSET_LIMIT, BODY_CURSOR and HEADER_CURSOR. Defaults to limit when blank.

Default batch size

Page size sent with OFFSET_LIMIT, BODY_CURSOR and HEADER_CURSOR. When 0, Hop falls back to an internal default (100).

Cursor JsonPath

JsonPath expression against a JSON response body to read the next cursor token, for every cursor strategy.

Cursor XPath

XPath expression against an XML response body to read the next cursor token, for every cursor strategy.

Next page URL JsonPath

JsonPath expression that reads the next page URL out of a JSON response body (BODY_NEXT_URL).

Next page URL XPath

XPath expression that reads the next page URL out of an XML response body (BODY_NEXT_URL).

Pagination strategies

Strategy How the next page is determined

Strategy	How the next page is determined
`NONE`	No pagination metadata is applied. Use this for single-request APIs.
`LINK_HEADER`	Follows the RFC 5988 `Link` response header: Hop requests the bracketed URI whose `rel` relation includes `next`. GitHub, Shopify, and similar APIs use this style. Hop stops when no `next` link is present or when the same URL would be requested again (cycle guard).
`OFFSET_LIMIT`	Adds offset/limit (or custom-named) query parameters. After each successful non-empty page, the offset increases by the batch size. An empty page ends the loop.
`PAGE_NUMBER`	Adds a page query parameter starting at `1` and increments it after each successful non-empty page. An empty page ends the loop.
`CURSOR`	Adds a cursor query parameter on follow-up requests. The token is extracted from the previous response with JsonPath (JSON) or XPath (XML). An empty page or missing next token ends the loop.
`BODY_CURSOR`	Merges the cursor and batch size into the request body of a `POST`, `PUT` or `PATCH` (JSON or form url-encoded, following the application type). On a `GET` they are sent as query parameters instead, because HTTP clients do not send a `GET` body. The loop ends when the next cursor is empty — not when a page is empty, since APIs of this shape (Slack, for example) can return sparse pages while still advertising a next cursor.
`HEADER_CURSOR`	Sends the cursor as a request header rather than a parameter. The next token is read from the body as with `CURSOR`, and an empty token ends the loop.
`BODY_NEXT_URL`	Reads an absolute next-page URL out of the response body with JsonPath or XPath and requests it as-is on the next iteration. Same loop semantics as `LINK_HEADER`, including the cycle guard.

NONE

No pagination metadata is applied. Use this for single-request APIs.

LINK_HEADER

Follows the RFC 5988 Link response header: Hop requests the bracketed URI whose rel relation includes next. GitHub, Shopify, and similar APIs use this style. Hop stops when no next link is present or when the same URL would be requested again (cycle guard).

OFFSET_LIMIT

Adds offset/limit (or custom-named) query parameters. After each successful non-empty page, the offset increases by the batch size. An empty page ends the loop.

PAGE_NUMBER

Adds a page query parameter starting at 1 and increments it after each successful non-empty page. An empty page ends the loop.

CURSOR

Adds a cursor query parameter on follow-up requests. The token is extracted from the previous response with JsonPath (JSON) or XPath (XML). An empty page or missing next token ends the loop.

BODY_CURSOR

Merges the cursor and batch size into the request body of a POST, PUT or PATCH (JSON or form url-encoded, following the application type). On a GET they are sent as query parameters instead, because HTTP clients do not send a GET body. The loop ends when the next cursor is empty — not when a page is empty, since APIs of this shape (Slack, for example) can return sparse pages while still advertising a next cursor.

HEADER_CURSOR

Sends the cursor as a request header rather than a parameter. The next token is read from the body as with CURSOR, and an empty token ends the loop.

BODY_NEXT_URL

Reads an absolute next-page URL out of the response body with JsonPath or XPath and requests it as-is on the next iteration. Same loop semantics as LINK_HEADER, including the cycle guard.

For LINK_HEADER and BODY_NEXT_URL, the path on the REST client transform is still relative to Base URL on the first request. Subsequent requests use the absolute URL the API returned.

Samples

github-releases.json — public GitHub API, LINK_HEADER pagination (used by rest-client-github-releases-loop.hpl in the REST transform samples project).