Database Table Endpoints
Goal: Publish a container's documents over HTTP, and control which operations exist.
A container's API is configured on the container itself, once, for the whole workspace. Nothing about it is decided on a surface.
Where a container's API is configured
- Select the Database node and, in the inspector, choose Manage containers.
- On the Containers tab, expand the container's row. Its section What this container publishes says: "Nothing is published until you switch methods on here. Published endpoints are listed in API Manager."
- Switch API enabled on, then switch on the methods you want, and press Save API settings.
| Switch | What it publishes |
|---|---|
| API enabled | The container's API as a whole. Switching it off unpublishes every method at once; the methods are kept for when you switch it back on |
| Create | Add new documents |
| Read | List documents and fetch one by id |
| Update | Replace an existing document |
| Delete | Delete a document by id. This removes the data |
The row also shows the container's Endpoint, ready to copy.
The endpoints you get
The table path is the document collection. There is no separate /documents segment.
GET /ox-api/data-stores/{store}/databases/{database}/tables/{table}
POST /ox-api/data-stores/{store}/databases/{database}/tables/{table}
GET /ox-api/data-stores/{store}/databases/{database}/tables/{table}/{documentId}
PUT /ox-api/data-stores/{store}/databases/{database}/tables/{table}/{documentId}
DELETE /ox-api/data-stores/{store}/databases/{database}/tables/{table}/{documentId}
The host is https://openx.fathym.com. There are also two batch routes, POST .../tables/{table}/batch/read and
POST .../tables/{table}/batch/transaction.
The path names both a store and a database, and they have to agree. A database reached through a store that
does not own it is refused as a wrong address (DATABASE_NOT_IN_STORE), not as a permission problem.
A plain PUT replaces the document; ?upsert=true creates or replaces it, and needs both Create and
Update switched on.
Addressing a single document
Cosmos addresses a document by id and partition key together. If your table is partitioned on anything
other than /id, pass the value as a query parameter:
PUT /ox-api/data-stores/ops-store/databases/ops/tables/readings/rec-8842?partitionKey=device-17
On a PUT, the value may instead be read from the document body at the table's partition path.
NOTE
Leave it out on a partitioned table and the request is refused with 400 PARTITION_KEY_REQUIRED - OpenX
will not guess a partition key. This is the most common cause of a read, update or delete of one document
that looks broken on an otherwise healthy table.
What "not switched on" does
A container publishes only what it explicitly switches on. A container with no API settings at all publishes nothing, and so does one with API enabled off.
An operation that is not switched on is absent from the listing, and refused if a client calls the
path anyway. /ox-api/openapi and the API Manager list, for each container, only the operations it publishes -
not every path the platform could serve.
Two separate narrowings decide what you see in that listing, and neither implies the other: what the workspace publishes, and what your own access rights let you see. An entry missing from your listing may be switched off, or may simply not be yours to see.
Access rights
Each call also needs the matching access right: Workspace.DataStore.Table.Read, .Create, .Update or
.Delete. A caller without it is refused with 403 DATA_STORE_RIGHT_MISSING before anything else is
checked.
When a request is refused
After the access right, the checks run in order - database, then store ownership, then table, then whether the container publishes an API at all, then the individual operation:
| What is wrong | Code | Status |
|---|---|---|
| The caller lacks the access right | DATA_STORE_RIGHT_MISSING | 403 |
| No such database in this workspace | DATABASE_NOT_FOUND | 404 |
| That database is not in this store | DATABASE_NOT_IN_STORE | 404 |
| No such table in that database | TABLE_NOT_FOUND | 404 |
| The container publishes no API | TABLE_NOT_EXPOSED | 404 |
| That operation is not switched on | OPERATION_NOT_EXPOSED | 403 |
| A partition key is needed and was not supplied | PARTITION_KEY_REQUIRED | 400 |
The order is deliberate: being told an operation is disabled, when the database is not in that store at all, sends you to fix the wrong thing. Errors from the store itself are listed in Data Stores troubleshooting.
NOTE
Your account, your keys
The CosmosDB account is yours. A write made straight at it with your own credentials never passes through OpenX, so the access rights above do not apply to it.
Next steps
| If you want to... | Go to... |
|---|---|
| Try the endpoints interactively | API Manager |
| Create or manage containers | Containers |
| Get a token | Auth & Tokens |
| Query the data from a surface | Warm Queries |