Skip to main content

Concepts

The handful of things OpenDBAPI is made of, and how they fit together.

Workspace​

A workspace belongs to a team and holds its own datasources, endpoints, service accounts, secrets, policies and activity. Workspaces share nothing, and PostgreSQL row-level security keeps one workspace's data out of another's queries. The workspace's slug is part of every endpoint URL:

https://opendbapi.example.com/api/{workspace}/{path}

People join a workspace as members with a role; see Members and roles.

Datasource​

The database an endpoint queries (PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, Trino, StarRocks, Apache Doris or ClickHouse), or an HTTP API it sends requests to. A datasource holds the connection settings and a password (encrypted, or a reference to a secret). Mark it read only when its endpoints should never change data. See Datasources.

Endpoint​

A query plus its URL, parameters, response shape, cache and limits. An endpoint has a draft you edit and numbered, frozen versions you publish:

StateMeaningAnswers calls
DraftCreated, never publishedNo
LiveA version is published. The header shows Live · v2, and Unpublished changes when the draft is aheadYes
DisabledTaken out of service; keeps its live version and grants, so Enable brings it back as it wasNo
In the trashSoft-deleted; restore it to edit it againNo

Callers only ever see a published version. Saving the draft changes nothing for them until you press Publish. See Endpoints.

Service account, client and grant​

Programs call private endpoints with a token. Three things decide who may call what:

  • A service account is a machine identity, such as reporting or partner-acme.
  • A client is a client_id and client_secret that belongs to a service account. A program exchanges them for a short-lived token at POST /oauth2/token.
  • A grant lets a service account call one endpoint, or every endpoint of a group. Without one, its calls get 403 not_granted.

Public endpoints need no token and answer anyone who can reach the server. See Clients and tokens.

Data policies​

Rules that change what callers see, per column or per row: masks (show a***@example.com instead of an email) and row filters (a service account only sees the rows of its own country). See Data policies.

Configuration as code​

A workspace exports as YAML documents that refer to each other by name. Keep the file in Git and apply it to another workspace or installation; an environment maps the file's datasource names to that workspace's datasources. See Configuration as code.