Skip to Content

API overview

Which programs have an API, how to call an operation, and the documents the reference is made from.

rookeryd and rookery serve answer the same kind of API. Each of their operations has a name, such as sessions.start or kv.set, and can be called in two ways.

ProgramRuns onReached atReference
rookerydevery host, as rootunix sockets in /run/rookeryrookeryd
rookery serveyour machine, or a servera unix socket of your user, and optionally TCProokery serve

rookery serve passes rookeryd's operations through to the host it names, under /v1/hosts/NAME/controller, so a program that talks to rookery serve reaches all hosts. It does not pass through endpoints.connect, which it opens itself for resources.connect. It also lists what can be done to each host and to the installation as actions, and runs one as a job it keeps.

Ways to call an operation

WayFor
The portalOne WebSocket at /v1/portal for many calls and streams at once. Rookery's server mode uses it
HTTPOne request per call, at the operation's path. Simple to try with curl, and the way to move more than 8 MB
A stream's own WebSocketEach streaming operation is also a WebSocket at its path, for a client that follows only one thing

Every operation page shows the portal frame and the HTTP request side by side.

Calls and streams

A call takes arguments and input and gives back a result. After it opens, a stream keeps sending frames, such as a session's output or new channel messages, and some streams take frames back, such as typed input. On the portal a stream is a subscription. See Streams for what all streams have in common.

The API number

version answers with api, a number that rises when something is added to the API. A client compares it to see what a host or a server can do. In rookery serve, hosts.list gives each host's number too.

apiAdded
2What the list below names

What number 2 adds:

  • ports.connect, with windows on the portal's streams
  • Roles from the keys of an object claim
  • The dropped frame of events.follow, inbox.follow and kv.follow
  • Host and resource changes on events.follow
  • The endpoints of a resource, and resources.connect to them
  • endpoints.connect of rookeryd, which rookery serve alone opens, to reach an endpoint of a resource on a node
  • The exec action of a resource

Rookery needs number 2 for a host's actions and port forwarding, and says to update the controller or apply the host until it has it.

Who may call

rookeryd answers on two sockets, and each operation says which may use it:

SocketLevelWho connects
/run/rookery/control.sockhostroot. Rookery reaches it over SSH with sudo -n rookeryd connect
/run/rookery/agent.sockagentthe agent account; box uses it

In a container rookeryd runs for the agent alone, without systemd, and calls that need systemd or another user are refused.

rookery serve has no levels. Its unix socket is readable by your user only, and over TCP every request and the portal need the token from serve.token as a bearer. See rookery serve.

Errors

Over HTTP an error is a status code with a JSON body; on the portal the same object comes back under the request's id:

{ "error": { "code": "not_found", "message": "No session k3v9qz2m8w1x", "status": 404 } }

Over HTTP the header rookery-error repeats the code, and rookery-error-message the start of the message, percent-encoded. A WebSocket client that is refused during the handshake often sees only the head of the answer, so it reads both there.

StatusCodeMeans
400bad_requestAn argument or the input is missing or malformed
401unauthorizedNo token, or the wrong one
403forbiddenThis level may not call the operation
404not_foundNo such operation, session, host or key
409conflictThe thing is in a state that does not allow this, such as a host that another action is changing
412precondition_failedSomeone else wrote in between
413too_largeThe input, or bytes on the portal, are too large
429limitToo many at once
500internalSomething failed inside
501not_availableNot available here, such as systemd in a container, this operation on the portal, or an action that cannot run now
502unreachablerookery serve could not reach the host
503not_servedNobody serves that service right now
504timeoutA service did not answer in time
520service_errorA service answered with an error

The documents

The reference is generated from documents that the programs print and the tests keep current. Use them for tooling:

DocumentPrinted byDownload
Operations of rookerydrookeryd operationsrookeryd.operations.json
Operations of rookery serverookery server api operationsrookery.operations.json
OpenAPI 3 of rookerydrookeryd openapirookeryd.openapi.json
OpenAPI 3 of rookery serverookery server api openapirookery.openapi.json
AsyncAPI 3 of rookerydrookeryd asyncapirookeryd.asyncapi.json
AsyncAPI 3 of rookery serverookery server api asyncapirookery.asyncapi.json

An operations document describes each operation with its name and HTTP route, arguments and errors, and input and result schemas. For streams it adds the frames each way. components holds the JSON schemas the $refs point at. The rookery serve document has "hosts": true: every rookeryd operation is available there with a host.

For agents

The whole site is also plain Markdown, for an assistant or a script that should learn how to work with Rookery.

AddressHolds
/llms.txtEvery page with a one-line description and a link to its Markdown
/llms-full.txtEvery page in one file
/md/PAGE.mdOne page, such as /md/api/portal.md or /md/api/host/sessions.md

Each page has a button at its top that copies its Markdown.

Edit on GitHub

Last updated on

On this page