Skip to main content

Endpoint settings

The Settings tab of an endpoint controls how it is listed, how results are paged and shaped, caching, streaming, limits, parameter rules and alerts. Changes take effect when you publish.

The Settings tab of the Customers endpoint with the Endpoint and Pagination groups

Endpoint​

SettingWhat it does
NameHow it is listed
DescriptionShown in the generated API documentation
MethodFixed while live: callers depend on it. Disable the endpoint to change it
PathFixed while live, for the same reason. {name} segments become path parameters
AccessPrivate needs a client token; Public answers anyone
GroupA folder for the list; not part of the URL

Pagination​

SettingWhat it doesDefault
PaginateCallers ask for one page at a time; OpenDBAPI adds the paging clause for the databaseOff
Default page sizeRows per page when the caller does not pass size20
Largest page sizeThe biggest size a caller may ask for500
Count totalOffset mode: adds a COUNT query per call and returns meta.total; off returns only meta.hasNextOn
ModeOffset uses page and size. Keyset returns a cursor for the next page: steady under inserts and fast on deep pages, but no jumping to page NOffset
Key columnsKeyset mode: the result columns the pages are ordered by; never null and together unique, so end with an id. Mark a key Newest / largest first to page downwards—

With pagination on, page, size, after and format are reserved parameter names.

GET /api/demo/v1/customers?page=2&size=20       offset mode
GET /api/demo/v1/events?size=50&after=eyJr… keyset mode: after = meta.nextCursor of the previous page

Output​

SettingWhat it does
ShapeList (an array of rows), Single object (the first row; no row answers 404 not_found), or Scalar value (the first column of the first row)
Key namesAs in SQL, or camelCase, which turns created_at into createdAt
Value typesConvert a column's values: Decimal as text (money as text, so JavaScript keeps every digit), ISO 8601 date, Epoch milliseconds, Boolean (0/1)
NestingGroup flat join rows into objects with collections: choose the id column, then a collection per prefix (e.g. order_ columns into orders)

Cache​

SettingWhat it doesDefault
Cache answersKeep successful GET answers in memory and serve them again until they expire; meta.cached tells callersOff
Keep forSeconds, up to 86 400 (one day)60
Shared between callersOne entry for all callers instead of one per service account. Not allowed when data policies make answers differ per callerOff

Clear cache drops this endpoint's cached answers. Try-it calls are never cached. Cached answers are kept per server instance, up to 128 MB (opendbapi.cache.max-bytes).

Streaming​

SettingWhat it does
Allow streamingCallers may ask for ?format=ndjson or ?format=csv (or the Accept header) to receive rows as they are read, without pagination
FormatsNDJSON, CSV, or both
Most rows streamedEmpty is the same as Most rows returned; up to 10 000 000

Limits​

SettingWhat it doesDefault
TimeoutSeconds; the query is cancelled after this and the caller gets 504 query_timeout30
Most rows returnedMore rows are cut off and meta.truncated is set10 000
Rate limitCalls per minute this endpoint answers across all callers; more answer 429 rate_limited with Retry-AfterNone
TransactionRun all statements in one transaction; any failure rolls them all backOff

Workspace-wide limits per client and per IP address are in Security.

Parameter rules​

Checks across parameters that run before the query, written in the same expression language as <if test>, each with a Message for callers. A rule that does not hold (or cannot be evaluated) answers 400 rule_failed with the message. At most 20 rules.

from == null or to == null or from <= to       "from must be before to"
ids == null or ids.size() <= 100 "Pass at most 100 ids"

Alerts​

Alert on failures sends server errors (5xx) to the workspace's alert channels, at most once per error every few minutes.

Further reading​