3forge Data APIs¶
The 3forge Data APIs are the two surfaces an external system uses to work with Center data: a REST API for request/response access, and a WebSocket streaming API for live subscriptions. Both reach the same tables, each with its own authentication setting, and both are built into an AmiCore process: you turn each one on with a property.
Features¶
- Query any Center table as JSON: run SQL over HTTP and get a result envelope a script can parse, with no client library to install.
- Insert, update, and upsert rows: write into Center tables from an OMS, an algo, or an ETL job over the same endpoint.
- Call server-side procedures: invoke a stored procedure and read back what it returned.
- Subscribe to live row changes: stream inserts, updates, and deletes over WebSocket, with the filter applied on the server.
- Authenticate with your existing users: REST accepts Basic or cookie auth through the Web's authentication plugin by default, and the WebSocket checks Basic credentials with the plugin you configure for it.
The two surfaces¶
Use the REST API when you want an answer now: run a query, insert rows, or call a procedure and read the result. Use the WebSocket streaming API when you want to keep watching: subscribe to a table and receive the initial snapshot followed by a live stream of row changes.
| REST API | WebSocket streaming API | |
|---|---|---|
| Shape | Request/response (pull) | Subscribe, then live push |
| You send | GET /3forge_rest/query?cmd=<AMI SQL> |
{"action":"subscribe","sql":"SELECT … FROM <table>"} |
| You get back | A result set (text, pipe, or JSON) |
The current rows and a snapshot marker, then conflated updates (add / update / delete) |
| Can write? | Yes: INSERT, UPDATE, DELETE, CALL |
No: subscribe-only |
| Reaches | https://<host>:<web-port>/3forge_rest/… |
ws://<host>:3410/<component> |
| Auth | HTTP Basic or an existing Web-session cookie | HTTP Basic on the connection handshake |
Together they cover the full round trip: write with REST, watch with WebSocket. The Quickstart does exactly that: inserts a row over REST and sees it arrive live over a WebSocket subscription.
Both are off until you enable them¶
Enable before you start
Out of the box, the REST query endpoint and the WebSocket server are both disabled. Nothing below works until you turn them on:
- REST SQL: the
queryendpoint is excluded by the shippedami.rest.plugin.classes=*,!QUERY,!ADMIN. AddQUERYto enable it. - WebSocket: the server opens only when
ami.websocket.portis set (the shipped line is commented out).
See Configuration for the exact properties.
Where to go next¶
| Page | What it covers |
|---|---|
| Concepts | Pull vs push, how each surface authenticates, and how a WebSocket WHERE uses AMI expression syntax rather than ANSI SQL |
| Quickstart | Enable both, insert a row over REST, and watch it arrive over a WebSocket subscription |
| REST API | Endpoints, /query parameters, response formats, and authentication |
| WebSocket streaming API | Connecting, subscribing, the message frames, conflation, and focus filtering |
| Configuration | Every ami.rest.* and ami.websocket.* property, TLS, and ports |
| Troubleshooting | The common errors from both surfaces and what they mean |