Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/docs/rest-and-object-messages.md
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
rest-and-object-messages.md · 3.4 KB · 147 lines

REST And Object Messages

DBBASIC should be RESTful where it exposes resources and direct where it executes behavior.

The goal is not to pretend every operation is pure REST. The goal is to keep a clean split:

flowchart LR
    A["HTTP API"] --> B["Resources"]
    A --> C["Object messages"]
    A --> D["Streams"]

    B --> B1["source"]
    B --> B2["state"]
    B --> B3["logs"]
    B --> B4["files"]
    B --> B5["versions"]
    B --> B6["metadata"]

    C --> C1["execute method"]
    C --> C2["run job"]
    C --> C3["handle webhook"]
    C --> C4["perform admin action"]

    D --> D1["WebSocket events"]
    D --> D2["Server-Sent Events"]

Why This Matters

Many APIs called REST are really RPC over HTTP:

POST /doThing
POST /executeAction
POST /api/run

That shape is easy to add, but it hides what the system actually owns. DBBASIC objects own real resources: source, state, logs, files, versions, and metadata. Those should be exposed as resources with stable paths, predictable HTTP methods, status codes, and JSON representations.

Object behavior is different. Executing an object is message passing. Jobs, events, webhooks, and realtime commands are also messages. They should be documented as messages instead of disguised as fake CRUD resources.

RESTful Resource Surface

DBBASIC should keep these resource-style endpoints boring and predictable:

GET /objects
POST /objects
GET /objects/{object_id}?source=true
PUT /objects/{object_id}?source=true
GET /objects/{object_id}?state=true
GET /objects/{object_id}?logs=true
GET /objects/{object_id}?versions=true
GET /objects/{object_id}?version=N
DELETE /objects/{object_id}?destroy=true

These endpoints expose things the object server owns.

They should preserve:

  • stable object identity
  • standard HTTP status codes
  • JSON response shapes existing clients can keep using
  • explicit authorization checks
  • useful cache behavior where safe
  • compatibility with docs/http-api-contract.md

Object Message Surface

Object execution is not only CRUD. It is behavior:

GET /objects/{object_id}
POST /objects/{object_id}
PUT /objects/{object_id}
DELETE /objects/{object_id}

Those calls deliver a method and payload to the object.

That model is closer to:

object_id + method + payload -> result

than:

table + row + CRUD operation

This is intentional. A DBBASIC object can represent a report, worker, webhook, view, business process, queue handler, generated UI, or admin tool.

Rollback

Rollback is the awkward case:

POST /objects/{object_id}
{"action": "rollback", "version_id": 1}

That is a message, not a pure REST resource update. It is kept for compatibility with existing clients.

Future server code may add a cleaner resource-style alias, but it should not break the existing message shape without a migration:

POST /objects/{object_id}/versions/{version_id}/rollback

Design Rule

Do not turn every operation into /api/doThing.

Use resources for object-owned data:

source, state, logs, files, versions, metadata

Use messages for object-owned behavior:

execute, run, handle, repair, migrate, broadcast

Use streams for object-owned realtime feedback:

source changed, state changed, log appended, version saved, execution failed

That is the honest shape of DBBASIC: REST where resources are real, object messages where behavior is real, and streams where live feedback is real.