External API Reference

This document contains reference information about Eyre's external APIs including the channel system and scries. Each section will also have practical examples in the Guide document.

Authentication

To use Eyre's channel system, run threads or perform scries you must first obtain a session cookie by authenticating with the following HTTP request:

See the Guide for an example of how to do this using the curl.

Eyre's response will include a set-cookie header like:

set-cookie: urbauth-~zod=0v4.ilskp.psv00.t09r0.l8rps.3n97v; Path=/; Max-Age=604800

The urbauth-{...} cookie provided must be included in a cookie header with all subsequent requests like:

cookie: urbauth-~zod=0v4.ilskp.psv00.t09r0.l8rps.3n97v

Channels

Eyre's channel system is the primary way of interacting with Gall agents from outside of Urbit.

Data from an external HTTP client is sent to Eyre as an HTTP PUT request containing one or more action JSON objects. Clients must obtain a session cookie by authenticating with Eyre in order to make such requests.

Data from Eyre is sent back to the external HTTP client on a channel as SSEs (Server Sent Events↗) containing a response JSON object.

A new channel is automatically created whenever a client sends an action in an HTTP PUT request to http{s}://{host}{port}/~/channel/{uid} with a new uid. To connect to the channel and receive any pending events, you just send an HTTP GET request with a valid session cookie to that URL.

The response you'll get to the GET request will be an event stream. Events will come in like:

id: 0
data: {"ok":"ok","id":1,"response":"poke"}

If you're working with Javascript in the browser context you'll handle these with an EventSource object or by using fetch and ReadableStream. If you're using another language, there'll likely be a library available to handle SSEs.

All the events that Eyre sends you on a channel must be acked so that Eyre can forget about them and clear them from the channel state. If facts (as diffs) from Gall agents to which you've subscribed are left unacked long enough, Eyre will consider the particular subscription clogged and automatically unsubscribe you. Note that acking one event will implicitly ack all previous events.

When you're finished with a channel, you can send Eyre a delete action to close it.

See the Using the Channel System section of the Guide document for a practical example.

HTTP Requests

Actions are sent to Eyre in HTTP PUT requests:

The cookie header contains the session cookie obtained by authenticating. The data is a JSON array containing one or more JSON action objects. The channel uid is a unique name of your choosing. Typically you'd use the current unix time and a hash but there's no specific requirements. If you're opening a new channel you'd choose a new uid and if you already have a channel open you'd just use that.

If successful, Eyre will respond with a status code of 204. Note the HTTP response will have no content, any responses will be sent as SSEs on the channel event stream.

Actions

Poke

This is for poking a Gall agent.

Example

{
  "id": 1,
  "action": "poke",
  "ship": "zod",
  "app": "hood",
  "mark": "helm-hi",
  "json": "hello"
}

Response

Eyre will send a poke ack as an SSE event on the channel event stream.

Subscribe

This is for subscribing to a watch path of a Gall agent.

Example

{
  "id": 2,
  "action": "subscribe",
  "ship": "zod",
  "app": "graph-store",
  "path": "/updates"
}

Response

Eyre will send back a watch ack. If subscribing was successful, you will also begin receiving any diffs sent by the Gall agent on the specified path.

Ack

This is for acknowledging an SSE event. If you ack one event, you also implicitly ack all previous events. Events must be acked so that Eyre can forget them. If you leave facts (as diffs) unacked long enough, Eyre will consider the subscription clogged and automatically unsubscribe you.

Example

{
  "id": 3,
  "action": "ack",
  "event-id": 7
}

Response

Eyre will not respond to an ack action.

Unsubscribe

This is for unsubscribing from a Gall agent watch path to which you've previously subscribed.

Example

{
  "id": 4,
  "action": "unsubscribe",
  "subscription": 2
}

Response

Eyre will not respond to an unsubscribe action.

Delete Channel

This is for deleting the channel itself.

Example

{
  "id": 5,
  "action": "delete"
}

Response

Eyre will not respond to a delete action.

Responses

Poke Ack

This acknowledgement comes in response to a poke action. A poke ack with an ok key means the poke succeeded. A poke ack with an err key means the poke failed.

Positive Poke Ack

Example

{
  "ok": "ok",
  "id": 1,
  "response": "poke"
}

Negative Poke Ack

Example

{
  "err": "<error message and traceback>",
  "id": 1,
  "response": "poke"
}

Action Required

You must ack the event.

Watch Ack

This acknowledgement comes in response to a subscribe action. A watch ack with an ok key means the subscription was successful. A watch ack with an err key means the subscription failed.

Positive Watch Ack

Example

{
  "ok": "ok",
  "id": 2,
  "response": "subscribe"
}

Negative Watch Ack

Example

{
  "err": "<error message and traceback>",
  "id": 2,
  "response": "subscribe"
}

Action Required

You must ack the event.

Diff

All facts sent by a Gall agent on the path to which you've subscribed are delivered as diffs. Note that Eyre makes a best effort to convert the fact to a json mark. If it can't, Eyre will crash and close the subscription, and you won't receive any diff for the fact.

Example

{
  "json": { "foo": "bar" },
  "id": 3,
  "response": "diff"
}

Action Required

You must ack each diff that comes in the event stream.

Quit

A quit comes in when a subscription has been ended. You may be intentionally kicked by the Gall agent to which you're subscribed, but certain network conditions can also trigger a quit. As a result, it's best to try and resubscribe when you get a quit, and if the resulting watch ack is negative you can then conclude the quit was intentional and give up.

Example

{
  "id": 4,
  "response": "quit"
}

Action Required

You must ack the event and you may wish to try and resubscribe.

Scry

A scry is a read-only request for some data.

A scry takes the form of an authenticated HTTP GET request to a URL path with the following format:

http{s}://{host}/~/scry/{app}{path}.{mark}

The {app} is the name of the Gall agent you want to query, for example graph-store.

The {path} is a scry endpoint of the Gall agent in question. Eyre will always scry with a care of %x, so the {path} needn't specify that. For example, the /x/keys scry endpoint of graph-store would just be specified as keys.

The {mark} is the type you want returned. It needn't just be json as with the channel system, it can be any mark, with two conditions:

1. It must be possible to convert the mark produced by the specified scry endpoint to the mark you want returned.
2. It must be possible to convert the mark you want returned to a mime mark, otherwise Eyre can't encode it in the HTTP response.

If your session cookie is invalid or missing, Eyre will respond with a 403 Forbidden status. If the scry endpoint cannot be found, Eyre will respond with a 404 Missing status. If the mark conversions can't be done, Eyre will respond with a 500 Internal Server Error status. Otherwise, Eyre will respond with a 200 OK status with the requested data in the body of the HTTP response.

See the Scrying section of the Guide document for a practical example.

Spider

See the HTTP API section of the Threads documentation.