[TODO: some of the DB details should get moved to Remix Database .]
[TODO table of contents]
Remix devs: there are more internal notes on this server here: ‣.
Unless otherwise noted, endpoints with specific parameters accept them as “form values”, with the following precedence:
application/x-www-form-urlencoded body (for PUT/PATCH/POST requests)If the same parameters is passed multiple times, we take the first.
Database endpoints all take the form /<app_name>/*, where app_name is
arbitrary but must be at least two characters long, and can't start or end in
whitespace. You must create an app before using it; see the documentation for
the /<app_name> endpoint below. The server manages an arbitrary number of
apps, each of which corresponds to its own database.
To any app-related URL you can add the query parameter "inmem". If this is set
to "true", instead of a persistent app, an in-memory one is accessed, with a
name given by the URL as usual. On-disk and in-memory apps have separate
namespaces, so you can use on-disk and in-memory apps with the same name, and
they are completely distinct. In-memory apps survive for the life of the server
process. Currently, this is typically a few days, so do not rely on in-memory
apps for anything non-ephemeral.
Basic CRUD operations on documents are available at /<app>/documents. Creating
a document is a POST to /<app>/documents, which returns a string ID on
success. The created document's URL is now /<app>/documents/<id>; you can
retrieve the document with a GET, update it with PUT, and delete it with DELETE.
All documents are represented as basic maps with string keys. They can be retrieved in three encodings: JSON, MessagePack binary, or MessagePack plus Base64 encoding for plain ASCII. For all endpoints accepting or returning structured data, JSON is the default format. You can select which you want, for both input and output, with the Accept and Content-Type headers:
use application/json, application/msgpack, or application/msgpack+base64,
respectively. There is also legacy support for specifying both input and output
formats with a URL path suffix: .json, .mp, or .mp64.
You can also upload to any POST or PUT endpoint with HTTP form data, provided
your data consists only of an object with string keys and values. Indicate this
by using the Content-Type: application/x-www-form-urlencoded header.
Warning: curl by default sets Content-Type to
application/x-www-form-urlencoded if you pass body data and don't set this
header. So when making PUT and POST requests with curl, always set this header
explicitly, or the server will misinterpret it.
Finally, a few endpoints, like invoking an agent and selecting a specific field
value from the output, might return a value other than a JSON/MessagePack
object. In these cases you can also set the Accept header to text/html,
text/javascript, or text/plain. If you specify a text encoding, but the
response isn't a string or byte array, the server falls back to JSON.