Connector
REST API
Call any HTTP/JSON API: read it as a source, enrich rows against it, or push rows to it. Pagination, retries and auth are handled for you.
Settings
What the connection form asks for. Every connection has a Staging side, which it needs, and an optional Production side with values of its own; both ask for the same settings.
| Base URL | The API root every node path is appended to, e.g. https://api.example.com/v1. |
| Default headers | Sent on every request, one 'Name: value' per line (e.g. Accept: application/json). |
| Timeout (seconds) | Per-request wall clock. Blank uses 30 seconds. |
| Method | How the API authenticates. Only the fields this method needs are shown, and only those are ever sent. Choices: No authentication; Bearer token; HTTP Basic (username + password); API key in a header; API key in a query parameter; OAuth2 client credentials; OAuth2 password grant; OAuth2 JWT bearer (signed with a private key). |
| Bearer Token | Shown when Method is Bearer token. Stored encrypted, and never shown again after you save it. |
| Username | Shown when Method is HTTP Basic (username + password) or OAuth2 password grant. |
| Password | Shown when Method is HTTP Basic (username + password) or OAuth2 password grant. Stored encrypted, and never shown again after you save it. |
| Key name | The header or query-parameter name the key travels in, e.g. X-API-Key. Shown when Method is API key in a header or API key in a query parameter. |
| API Key | Shown when Method is API key in a header or API key in a query parameter. Stored encrypted, and never shown again after you save it. |
| Token URL | The OAuth2 token endpoint the credentials are exchanged at, e.g. https://oauth2.googleapis.com/token. Shown when Method is OAuth2 client credentials or OAuth2 password grant or OAuth2 JWT bearer (signed with a private key). |
| Client ID | Shown when Method is OAuth2 client credentials or OAuth2 password grant. |
| Client Secret | Shown when Method is OAuth2 client credentials or OAuth2 password grant. Stored encrypted, and never shown again after you save it. |
| Issuer | Who the signed assertion comes from: a Google service account's client_email, or a Salesforce connected app's consumer key. Shown when Method is OAuth2 JWT bearer (signed with a private key). |
| Subject | Optional: the user to act as, when the provider asks for one. A Salesforce username, or a Google Workspace user under domain-wide delegation. Shown when Method is OAuth2 JWT bearer (signed with a private key). |
| Private Key | The PEM private key that signs the assertion, from -----BEGIN PRIVATE KEY----- to the END line. From a Google JSON key file, paste its private_key value. An encrypted key is refused. Shown when Method is OAuth2 JWT bearer (signed with a private key). Stored encrypted, and never shown again after you save it. |
| Key ID | Optional: sent as the assertion's kid header. A Google JSON key file's private_key_id. Shown when Method is OAuth2 JWT bearer (signed with a private key). |
| Signing algorithm | Choices: RS256 (an RSA key); ES256 (a P-256 EC key). Shown when Method is OAuth2 JWT bearer (signed with a private key). |
| Scope | Optional, and needed only if the provider requires one. Shown when Method is OAuth2 client credentials or OAuth2 password grant or OAuth2 JWT bearer (signed with a private key). |
| Audience | Optional. Client credentials send it with the token request; the JWT bearer method puts it in the assertion and uses the token URL when it is blank (Salesforce wants https://login.salesforce.com). Shown when Method is OAuth2 client credentials or OAuth2 password grant or OAuth2 JWT bearer (signed with a private key). |
Testing the connection
Test sends a request to the base URL and passes on any HTTP answer, because an API's root address is often not an endpoint. A pass proves the address is reachable, not that a token or key is right: the first run against a real endpoint does that. With an OAuth2 method, Test first exchanges the credentials for a token, so a wrong client ID, secret or private key does fail, with the provider's own reason.
Good to know
- The credentials go only to this connection's own host. A request a node addresses to any other host is refused, and a redirect to another host carries none of them.
- A request that only reads is retried after a dropped connection or a busy server. A request that may already have arrived is never sent twice.
- Only the fields the chosen sign-in method needs are shown, and only those are ever sent.
- OAuth2 JWT bearer is for providers that sign in with a private key instead of a secret: a Google service account, a Salesforce connected app with a certificate, DocuSign. Trinium signs a short-lived assertion with the key and exchanges it at the token URL each time it needs a token. Paste the whole key, BEGIN and END lines included; its line breaks are restored for you. An encrypted key is refused.
- With any OAuth2 method, when a token expires during a REST API Input or REST API Output run, Trinium gets a new one once and sends the request again.
Nodes that use it
API Batch Lookup
Send your rows to an API many at a time and add its answers as new columns.
API Lookup
Look up each row against an API and add the answer as new columns.
File from URL
Read one file from a web link: CSV, JSON, Parquet, Excel or XML.
REST API (Read)
Read records from an HTTP/JSON API, following its pagination to the end.
REST API (Write)
Push rows to an HTTP API, one record per request or many batched into one.