Skip to content

api-surface.md

Latest commit

 

History

History
176 lines (142 loc) · 8.99 KB

api-surface.md

File metadata and controls

176 lines (142 loc) · 8.99 KB
Raw

API Surface

ExtendDO exposes a DynamoDB JSON endpoint, a health endpoint, and a curl-friendly management API. The DynamoDB JSON endpoint targets ExtendDB parity. The management API is not an AWS Identity and Access Management REST API; it is a Worker-native interface for the ExtendDB management/auth surface.

HTTP Entry Points

Path Methods Purpose
/ POST DynamoDB JSON requests using x-amz-target.
/healthz GET Worker and wasm health check.
/management/... Multiple JSON management API.

DynamoDB JSON request bodies are capped at 16 MiB by the Worker entrypoint. Management request bodies are capped at 128 KiB.

DynamoDB JSON Endpoint

Send DynamoDB JSON requests to / with POST and an x-amz-target header such as DynamoDB_20120810.CreateTable.

The ExtendDB wasm engine handles validation, operation dispatch, expression and update evaluation, key-condition parsing, and DynamoDB response shaping. The Worker host provides storage through Durable Objects. For the implementation mapping behind each primitive, see DynamoDB Primitive Mapping.

Supported operation names in the current dispatch table:

  • Table/control plane: CreateTable, DeleteTable, DescribeTable, ListTables, UpdateTable, DescribeEndpoints, DescribeLimits.
  • Item and read operations: PutItem, GetItem, DeleteItem, UpdateItem, Query, Scan, BatchGetItem, BatchWriteItem.
  • Transactions: TransactGetItems, TransactWriteItems.
  • TTL and tags: DescribeTimeToLive, UpdateTimeToLive, TagResource, UntagResource, ListTagsOfResource.
  • Streams: DescribeStream, ListStreams, GetShardIterator, GetRecords.
  • Backups: CreateBackup, DescribeBackup, ListBackups, DeleteBackup, RestoreTableFromBackup, DescribeContinuousBackups, UpdateContinuousBackups, RestoreTableToPointInTime.
  • Import/export: ImportTable, ExportTableToPointInTime, DescribeExport, ListExports, DescribeImport, ListImports.

RestoreTableToPointInTime intentionally follows ExtendDB's current unsupported-operation behavior.

Import And Export

ExtendDB's upstream import/export handler is filesystem-based. ExtendDO replaces that runtime dependency with an R2 adapter while preserving the DynamoDB/ExtendDB request and response shapes where possible.

Import behavior:

  • ImportTable reads from FileSource.Path, interpreted as an R2 object key.
  • Supported input formats are DynamoDB JSON, ION-as-DynamoDB-JSON, and CSV.
  • The target table remains hidden while parsing and staging rows.
  • The R2 source object's etag/version is pinned before async processing.
  • The table becomes active only after staged rows commit successfully.

Export behavior:

  • ExportTableToPointInTime creates a snapshot-backed export session.
  • The requested destination is used as a prefix or base, but the final R2 object key is generated per export id to prevent collisions.
  • Export status is visible through DescribeExport and ListExports.
  • Exported objects include ownership metadata so recovery does not confuse a same-size object with the intended export.

Management Authentication

Management requests use HTTP Basic authentication:

  • Static bootstrap admin: EXTENDDO_ADMIN_USER and EXTENDDO_ADMIN_PASSWORD.
  • Stored admin users created through /management/admins.
  • User self-service identity: username account_id/user_name with the user's password.

Admin-only routes reject self-service callers unless the specific route allows the matching user.

Management Endpoint Matrix

Admin and settings:

Method Path Purpose
POST /management/admins Create stored admin.
GET /management/admins List admins.
DELETE /management/admins/<admin> Delete admin.
PUT /management/admins/<admin>/password Change admin password.
GET /management/settings List settings.
GET /management/settings/<key> Read setting.
PUT /management/settings/<key> Update writable setting.

Accounts:

Method Path Purpose
POST /management/accounts Create account.
GET /management/accounts List accounts.
DELETE /management/accounts/<account_id> Delete account.

Users:

Method Path Purpose
POST /management/accounts/<account_id>/users Create user.
GET /management/accounts/<account_id>/users List users.
DELETE /management/accounts/<account_id>/users/<user> Delete user.
PUT /management/accounts/<account_id>/users/<user>/password Change user password.
GET /management/accounts/<account_id>/users/<user>/policies List user policies.
PUT /management/accounts/<account_id>/users/<user>/policies/<policy> Put user inline policy.
DELETE /management/accounts/<account_id>/users/<user>/policies/<policy> Delete user inline policy.
PUT /management/accounts/<account_id>/users/<user>/permissions-boundary Put user boundary.
GET /management/accounts/<account_id>/users/<user>/permissions-boundary Get user boundary.
DELETE /management/accounts/<account_id>/users/<user>/permissions-boundary Delete user boundary.
PUT /management/accounts/<account_id>/users/<user>/tags Put user tags.
GET /management/accounts/<account_id>/users/<user>/tags List user tags.
DELETE /management/accounts/<account_id>/users/<user>/tags Delete user tags by request body.
DELETE /management/accounts/<account_id>/users/<user>/tags/<key> Delete one user tag.
POST /management/accounts/<account_id>/users/<user>/access-keys Create access key.
GET /management/accounts/<account_id>/users/<user>/access-keys List access keys.
DELETE /management/accounts/<account_id>/users/<user>/access-keys/<key> Delete access key.
PUT /management/accounts/<account_id>/users/<user>/access-keys/<key>/status Update access key status.
POST /management/accounts/<account_id>/users/<user>/access-keys/import Import access key.

Groups:

Method Path Purpose
POST /management/accounts/<account_id>/groups Create group.
GET /management/accounts/<account_id>/groups List groups.
DELETE /management/accounts/<account_id>/groups/<group> Delete group.
POST /management/accounts/<account_id>/groups/<group>/users Add user to group.
GET /management/accounts/<account_id>/groups/<group>/users List group users.
DELETE /management/accounts/<account_id>/groups/<group>/users/<user> Remove user from group.
GET /management/accounts/<account_id>/groups/<group>/policies List group policies.
PUT /management/accounts/<account_id>/groups/<group>/policies/<policy> Put group inline policy.
DELETE /management/accounts/<account_id>/groups/<group>/policies/<policy> Delete group inline policy.

Roles and sessions:

Method Path Purpose
POST /management/accounts/<account_id>/roles Create role.
GET /management/accounts/<account_id>/roles List roles.
DELETE /management/accounts/<account_id>/roles/<role> Delete role.
GET /management/accounts/<account_id>/roles/<role>/policies List role policies.
PUT /management/accounts/<account_id>/roles/<role>/policies/<policy> Put role inline policy.
DELETE /management/accounts/<account_id>/roles/<role>/policies/<policy> Delete role inline policy.
PUT /management/accounts/<account_id>/roles/<role>/permissions-boundary Put role boundary.
GET /management/accounts/<account_id>/roles/<role>/permissions-boundary Get role boundary.
DELETE /management/accounts/<account_id>/roles/<role>/permissions-boundary Delete role boundary.
PUT /management/accounts/<account_id>/roles/<role>/tags Put role tags.
GET /management/accounts/<account_id>/roles/<role>/tags List role tags.
DELETE /management/accounts/<account_id>/roles/<role>/tags Delete role tags by request body.
DELETE /management/accounts/<account_id>/roles/<role>/tags/<key> Delete one role tag.
POST /management/accounts/<account_id>/assume-role Assume role as current authenticated caller.
POST /management/accounts/<account_id>/roles/<role>/assume Admin assume role by caller ARN.

The router also accepts singular /policy/<policy>, /boundary, and group membership /members aliases for some endpoints. Prefer the plural /policies/..., /permissions-boundary, and /users paths in new documentation and scripts.

Removed AWS-Only Routes

Management routes for managed policies and policy versions, MFA devices, OIDC/SAML providers, federated assume-role flows, account organization context, trusted-network/FAS context, and request-tag condition context are intentionally not exposed. They are outside the ExtendDB parity target unless ExtendDB adds them upstream.