REST

Query data from any HTTP/HTTPS REST API using configurable methods, query parameters, headers, and request bodies.

Connection Settings

Main Configuration

Setting	Description	Example Value
Host	Base URL of the REST API server. Must start with http:// or https://.	http://server.com:8080
Accept unauthorized certificate	Allow HTTPS connections with self-signed or invalid certificates.	Enabled/Disabled
Timeout	Duration in seconds before a connection failure is reported. Default: 30.	30

Authentication

Setting	Description	Example Value
Authentication method	Authentication type for the connection.	None, Basic, Bearer, API Key
Username	Username for Basic authentication.	api_user
Password	Password for Basic authentication.	••••••••
Token	Bearer token sent in the Authorization header.	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
API Key	Name of the header or query parameter for API Key authentication.	X-Api-Key
API Value	Secret value sent with the request (stored encrypted).	••••••••
Add to	Where the API key/value pair is injected.	header, query-params

Proxy Configuration

Setting	Description	Example Value
Use proxy	Route requests through a proxy server.	Enabled/Disabled
Proxy URL	Full URL of the proxy server.	http://proxy.example.com:8080
Proxy username	Username for proxy authentication (if required).	proxy_user
Proxy password	Password for proxy authentication (if required).	••••••••

Connection Test

OIBus can test the connection to the server before any item query is executed. This is useful to verify credentials and reachability.

Setting	Description	Example Value
Method	HTTP method used for the test request. Default: GET.	GET
Test Endpoint	Path appended to the host. Default: /.	/health
Body	Optional JSON body for POST or PUT test requests.	{}
Success code	HTTP status code indicating a successful connection. Default: 200.	200

info

The test body is only sent when the method is POST or PUT.

Group Settings

Items can be organised into groups. Each group defines a shared collection schedule and default throttling settings. Items in the same group are still fetched one at a time in sequence — the group simply provides common defaults that individual items can override.

Setting	Description	Example Value
Name	Unique label for the group within this connector.	Group A
Scan mode	Schedule used to collect all items in the group.	Every 1 min
Throttling	Default throttling values (Max read interval, Read delay, Start time offset, End time offset, Recovery strategy) inherited by items in the group.	3600, 200, 0, 0, oldest

Item Settings

Each item targets a specific API endpoint and defines how to request and interpret the response. Items inherit their scan mode and throttling defaults from their group, but each setting can be overridden per item by disabling Sync with group.

Throttling Settings

Throttling controls how OIBus paces historical data requests. These settings appear on each group (for connectors that support groups) or on each item (for single-item connectors). Items in a group can override the group defaults by disabling the Sync with group toggle.

Setting	Description	Example Value
Max read interval	Maximum duration of each sub-query in seconds. Larger time ranges are automatically split into chunks not exceeding this value.	3600
Read delay	Pause in milliseconds between consecutive sub-queries. Helps prevent server overload and manages rate limits.	1000
Start time offset	Milliseconds added to the start of the query window (@StartTime). A negative value moves the start earlier, to capture late-arriving data from the previous interval — this is the old "Overlap" behavior. A positive value moves the start later instead, skipping that much of the window.	-60000
End time offset	Milliseconds added to the end of the query window (@EndTime). A negative value pulls the end in earlier — useful for eventually-consistent sources where the very latest rows aren't reliable yet. A positive value extends the window later. If the resulting end is not after the effective start, the query is skipped for this run.	0
Recovery strategy	Order in which OIBus catches up on a backlog of unqueried sub-intervals — e.g. after being stopped for a while, or on first run against a wide time range. From oldest to newest (default) processes the backlog chronologically. From newest to oldest queries the most recent sub-interval first, so up-to-date values become available immediately while older gaps are backfilled afterward.	From oldest to newest

How Throttling Works

1. Interval splitting — A 24-hour range with Max read interval = 3600 (1 hour) is split into 24 separate 1-hour sub-queries.
2. Read delay — A pause is inserted between sub-queries to manage server load.
3. Start/End time offset — With Start time offset = -60000 (-1 minute), a query for [10:00–11:00] actually requests [9:59–11:00], ensuring no late-arriving data is missed. End time offset shifts the other boundary the same way.
4. Recovery strategy — Only matters when there's more than one sub-interval to catch up on. With From newest to oldest, the tracked instant only advances once every sub-interval in the backlog has been queried — this avoids skipping over not-yet-queried older intervals if OIBus restarts mid-catch-up.

Offsets apply to the full query range

Start/End time offset are applied once, to the start and end of the overall query window — not to the start of each individual sub-interval when a large range is split into chunks by Max read interval.

Recommended Configurations

Scenario	Max read interval	Read delay	Start time offset
Stable network, small datasets	3600 (1 hour)	500	0 (none)
Unstable network	1800 (30 min)	2000	0 (none)
Large historical retrievals	7200 (2 hours)	1000	0 (none)
Real-time with occasional gaps	900 (15 min)	200	-15000 (-15 sec)

Going deeper

For the reasoning behind these numbers — sizing Max read interval against real data volumes, the Read delay / Max read interval trade-off on a large backlog, and worked examples of Start vs. End time offset (including the batched multi-item case where items don't all flush at once) — see Tuning South History Call Settings.

Request Configuration

Setting	Description	Example Value
Method	HTTP method for the data request. Default: GET.	GET
Endpoint	Path appended to the host.	/api/data
Return type	How the response is processed — as a structured body or a raw file download.	body, file

Query Parameters

Add key/value pairs appended to the request URL as query string parameters. Use the @StartTime and @EndTime variables to inject the query's time window directly into a parameter value.

Setting	Description	Example Value
Key	Name of the query parameter.	from
Value	Value of the parameter; may contain @StartTime or @EndTime placeholders.	@StartTime
Date format	Shown when the value contains @StartTime or @EndTime — configures how the instant is formatted.	iso-string

Date/Time Format for Query Parameters

When a parameter value includes @StartTime or @EndTime, a date format configuration section appears:

Setting	Description	Example Value
Type	Representation of the datetime value.	iso-string, unix-epoch, unix-epoch-ms, string
Timezone	Timezone for formatting (only for string type).	UTC, Europe/Paris
Format	Custom format pattern (only for string type).	yyyy-MM-dd HH:mm:ss

Headers

Add custom HTTP headers to the request. Like query parameters, header values support @StartTime and @EndTime substitution with the same date/time format configuration.

Setting	Description	Example Value
Key	Header name.	X-Custom-Header
Value	Header value; may contain @StartTime or @EndTime placeholders.	Bearer my_token

Content-Type

When a body is configured and no Content-Type header is explicitly defined, OIBus automatically adds Content-Type: application/json.

Request Body

A JSON body can be sent for POST, PUT, PATCH, and DELETE requests. The body supports @StartTime and @EndTime placeholders to inject the query time window into the payload.

Setting	Description	Example Value
Content	JSON body of the request; may contain @StartTime or @EndTime placeholders.	{"from": "@StartTime"}
Date format	Shown when the body contains @StartTime or @EndTime — configures how the instant is formatted.	iso-string

The date/time format configuration for the body follows the same settings as query parameters.

Response Handling

The Return type setting controls how OIBus interprets the server's response.

Setting	Description	Example Value
Return type	body: response is read as text; OIBus auto-detects JSON or XML from the Content-Type header. file: response body is saved as a binary file using the Content-Disposition filename if provided.	body, file

Filename in file mode

When the server does not provide a Content-Disposition header, the file is saved with an auto-generated name based on the connector name, item name, and a random identifier.

Tracking the Maximum Instant

When the return type is body and the response is JSON, OIBus can automatically track the most recent timestamp found in the response. This advances the @StartTime of the next query to avoid re-fetching already seen data.

Setting	Description	Example Value
Track instant	Enable extraction of the maximum timestamp from the JSON response.	Enabled/Disabled
JSONPath	Expression used to locate timestamp values inside the JSON response.	$.data[*].timestamp
Date format	How OIBus should interpret the extracted timestamp values (type, timezone, format, locale).	iso-string

Tracking Instant Date/Time Format

Setting	Description	Example Value
Type	Representation of the datetime in the JSON field.	iso-string, unix-epoch, unix-epoch-ms, string
Timezone	Timezone for parsing (only for string type).	UTC, Europe/Paris
Format	Custom format pattern for parsing (only for string type).	yyyy-MM-dd HH:mm:ss
Locale	Locale for month/day name parsing (only for string type).	en-En

JSONPath

OIBus uses the JSONPath Plus library. When multiple values match the JSONPath expression, the maximum timestamp among all of them is used as the new @StartTime.

Time Variables

The following variables can be used in query parameter values, header values, and request bodies:

Setting	Description	Example Value
@StartTime	Start of the current query interval. Updated to the tracked max instant after each query.	2024-01-15T10:00:00.000Z
@EndTime	End of the current query interval (capped to the current time or the sub-interval end).	2024-01-15T11:00:00.000Z

Query Splitting

When a large time range is requested, OIBus splits it into smaller sub-intervals based on the Max read interval throttling setting. Each sub-interval gets its own @StartTime / @EndTime pair.