@@ -0,0 +1,545 @@
2+title = "HTTP API Guide"
7+[Eyre] is the web-server [vane] (kernel module) of [Arvo], an Urbit ship's
8+kernel and operating system. In this guide, we'll look at interacting with a
9+ship through Eyre's web API using the [@urbit/http-api] Javascript module.
13+Before we dig into the details of Eyre's API, we'll first give a quick run-down
14+of some concepts in Arvo. Eyre's API is a fairly thin overlay on some of Arvo's
15+internal systems, so there's some basic things to understand.
19+[Clay] is the filesystem vane. It's typed, and it's revision-controlled in a
20+similar way to git. Clay is comprised of a number of [desk]s, which are a bit
21+like git repositories. Each app on your ship's home screen corresponds to a desk
22+in Clay. That desk contains the source code and resources for that app.
26+Most of Clay's workings aren't relevant to front-end development, but there's
27+one important concept to understand: [mark]s. Clay is a typed filesystem, and
28+marks are the filetypes. There's a mark for `.hoon` files, a mark for `.txt`
29+files, and so on. The mark specifies the hoon datatype for those files, and it
30+also specifies conversion methods between different marks. Marks aren't just
31+used for files saved in Clay, but also for data that goes to and from the web
34+When you send a [poke](#pokes) or run a [thread](#threads) through Eyre, it will
35+look at the mark specified (for example `graph-action-3`, `settings-event`, etc)
36+and use the corresponding mark file in the desk to convert the given JSON to
37+that datatype before passing it to the target [agent](#gall-agents) or thread.
38+The same conversion will happen in reverse for responses.
40+Note that Eyre makes a best effort attempt to convert data to and from JSON. If
41+the marks in question do not contain appropriate JSON conversion functions, it
42+will fail. Not all [scry endpoints](#scry-endpoints), [subscription
43+paths](#subscriptions), pokes, etc, are intended to be used from a front-end, so
44+not all use marks which can be converted to and from JSON (the `noun` mark for
45+example). If documentation is available for the agent or thread in question, is
46+should note in some fashion whether it can take or produce JSON. The majority of
47+things you'll want to interact with through Eyre _will_ work with JSON.
51+An _agent_ is a userspace application managed by the [Gall] vane. A desk may
52+contain multiple agents that do different things. The Groups app, for example,
53+has `graph-store`, `group-store`, `contact-store`, and others in its desk.
54+Agents are the main thing you'll interact with through Eyre. They have a simple
55+interface with three main parts:
59+Pokes are single, stand-alone messages to agents. Pokes are how you send data
60+and requests to agents. Agents will send back either a positive acknowledgement
61+(ack) or a negative acknowledgement (nack). The agent can't send actual data
62+back in the acks. If they have any response to give back, it will be sent out to
63+subscribers on a subscription path instead.
65+The pokes an agent accepts will be defined in the `on-poke` section of its
66+source in the desk's `/app` directory, and typically in its type definition file
67+in the `/sur` directory too. If the agent has documentation, the data structures
68+and marks of its pokes should be listed there.
70+`http-api` includes a `poke` function which allows you to perform pokes through
71+Eyre, and is [detailed below](#poke).
75+Agents define subscription paths which you can subscribe to through Eyre. A path
76+might be simple and fixed like `/foo/bar`, or it might have variable elements
77+where you can specify a date, ship, or what have you. Each agent will define its
78+subscription paths in the `on-watch` section of its source, and if it has
79+documentation the paths should also be listed there.
81+You can subscribe by sending a watch request to the agent with the desired path
82+specifed. The agent will apply some logic (such as checking permissions) to the
83+request and then ack or nack it. If acked, you'll be subscribed and begin
84+receiving any updates the agent sends out on that path. What you'll receive on a
85+given path depends entirely on the agent.
87+Agents can kick subscribers, and you can also unsubscribe at any time.
89+`http-api` includes a `subscribe` function which allows you to perform pokes through
90+Eyre, and is [detailed below](#subscribe).
94+Pokes and subscriptions can modify the state of the agent. A third kind of
95+interaction called a _scry_ does not - it simply retrieves data from the agent
96+without any side-effects. Agents can define _scry endpoints_ which (like
97+subscriptions) are paths. A scry to one of these endpoints will retrieve some
98+data (as determined by the agent's design) from the agent's state. Like
99+subscription paths, scry paths can be simple like `/foo/bar` or contain variable
100+elements. Unlike subscriptions, a scry is a one-off request and the data will
101+come back immediately.
103+Scry endpoints are defined in the `on-peek` section of an agent's source, and
104+will likely be listed in the agent's documentation if it has any. Scry endpoints
105+will often be written with a leading letter like `/x/foo/bar`. All scries
106+through Eyre are `x` scries, so that letter (called a `care`) needn't be
109+`http-api` includes a `scry` function which allows you to perform scries through
110+Eyre, and is [detailed below](#scry).
114+A thread is a monadic function in Arvo that takes arguments and produces a
115+result. Threads are conceptually similar to Javascript promises - they can
116+perform a series of asynchronous I/O operations and may succeed or fail. Threads
117+are often used to handle complex I/O operations for agents. Threads live in the
118+`/ted` directory of a desk.
120+`http-api` includes a `thread` function which allows you to run threads through
121+Eyre, and is [detailed below](#thread).
125+The `http-api` module provides convenient functions to interact with a ship
126+through Eyre. In this section we'll discuss the basics of how it works.
128+### Importing the module
130+The `http-api` module is available in npm as `@urbit/http-api`, and can be
134+npm i @urbit/http-api
137+Once installed, you can import it into your app with:
140+import Urbit from '@urbit/http-api';
143+Note that the examples in this guide are simple HTML documents with vanilla
144+Javascript in `<script>` tags, so they use [unpkg.com](https://unpkg.com) to
145+import `@urbit/http-api`. This is not typical, and is just done here for
146+purposes of simplicity.
150+All functionality is contained within the `Urbit` class. There are two ways to
151+instantiate it, depending on whether your web app is served directly from the
152+ship or whether it's served externally. The reason for the difference is that
153+you require a session cookie to talk to the ship. If your app is served from the
154+ship, the user will already have a cookie. If it's not, they'll need to
155+authenticate, which is [detailed separately below](#authentication).
157+In the case of a front-end served from the ship, the `Urbit` class contains a `constructor` which takes three arguments:
159+| Argument | Type | Description | Example |
160+| -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
161+| `url` | `string` | The host of the ship without the protocol. This is mandatory but would typically be left blank as requests will still work if they're root-relative paths. | `"example.com"`, `"localhost:8080"`, `""` |
162+| `code` | `string` | The web login code of the ship. You'll typically use this constructor when it's served directly from the ship and therefore you'll already have a session cookie, so this field is optional and is typically omitted or left empty. | `""`, `"lidlut-tabwed-pillex-ridrup"` |
163+| `desk` | `string` | The desk on which you want to run threads. This field is optional and is only used if you want to run threads, no other function uses it. If you're not running threads, you can omit it or leave it empty. | `"landscape"`, `""` |
165+To create an `Urbit` instance, you can simply do:
168+const api = new Urbit("");
171+If you want to specify a desk, you can do:
174+const api = new Urbit("", "", "landscape");
179+Most functions of the `Urbit` class need to know the ship name or they will
180+fail. This is given explicitly with the external authentication method [detailed
181+below](#authentication), but not when using the `Urbit` constructor in a web app
182+served directly from the ship. Rather than having the user manually enter it,
183+Urbit ships serve a JS library at `/session.js` that contains the following:
189+`"zod"` will be replaced with the actual name of the ship in question. You can
190+include this file like:
193+<script src="/session.js"></script>
196+Then you need to set the `ship` field in the `Urbit` object. You would typically
197+do it immediately after instantiating it:
200+const api = new Urbit("");
201+api.ship = window.ship;
206+With the exception of scries and threads, all communication with Eyre happens
207+through its channel system.
209+The `Urbit` object will generate a random channel ID that looks like
210+`1646295453-e1bdfd`, and use a path of `/~/channel/1646295453-e1bdfd` for
211+channel communications. Pokes and subscription requests will be sent to that
212+channel. Responses and subscription updates will be sent out to you on that
215+Eyre sends out updates and responses on an [SSE] (Server Sent Event) stream for
216+the channel. The `Urbit` object handles this internally with an `eventSource`
217+object, but you won't deal with it directly. Eyre requires all events it sends
218+out be acknowledged by the client, and will eventually close the channel if
219+enough unacknowledged events accumulate. The `Urbit` object handles event
220+acknowledgement automatically, so you don't need to worry about this.
222+Since the `Urbit` object handles channels internally, you don't typically need
223+to deal with them at all. There is, however, the [`delete()`](#delete-channel)
224+function if you want to close the whole channel and end all subscriptions at
227+Eyre automatically creates a channel when a poke or subscription request is
228+first sent to `/~/channel/[a new channel ID]`. If your web app is served
229+external to the ship and you use the `authenticate` function [described
230+below](#authentication), the function will automatically send a poke and open
231+the channel. If your web app is served directly from the ship and you use
232+`Urbit` class constructor, it won't open the channel right away. Instead, the
233+channel will be opened whenever you first send a poke or subscription request.
237+**If your front-end is served directly from the Urbit ship, this step can be
238+skipped.** If your web app is served externally to the ship, you must
239+authenticate and obtain a session cookie before commencing communications with
242+The `Urbit` class in `http-api` includes an `authenticate` function which does
245+1. Login to the user's ship with their `code` and obtain a session cookie.
246+2. Generate a random channel ID for the connection.
247+3. Poke the user's ship and print "opening airlock" in the dojo to initialize
250+The `authenticate` function takes four arguments in an object: `ship`, `url`,
251+`code` and `verbose`:
253+| Argument | Type | Description | Example |
254+| --------- | --------- | -------------------------------------------------------------------------------------- | --------------------------------- |
255+| `ship` | `string` | The ship ID (`@p`) without the leading `~`. | `"sampel-palnet"` or `"zod"` |
256+| `url` | `string` | The base URL for the ship without the protocol. | `localhost:8080` or `example.com` |
257+| `code` | `string` | The user's web login code. | `"lidlut-tabwed-pillex-ridrup"` |
258+| `verbose` | `boolean` | Whether to log details to the console. This field is optional and defaults to `false`. | `true` |
260+This function returns a promise that if successful, produces an `Urbit` object
261+which can then be used for communications with the ship.
263+**Note:** An Urbit ship will deny CORS requests from external URLs by default.
264+In order to allow CORS for an external web app, the user will need to run the
265+following in the dojo (replacing `https://example.com` with the address in
269+|cors-approve 'https://example.com'
274+Here's a simple example that will run `authenticate` for a fakezod when the
275+_Connect_ button is pressed:
278+<html> <head> <script
279+src="https://unpkg.com/@urbit/http-api"></script> </head> <body>
280+<button id="start" type="button" onClick="connect()" >Connect</button>
281+</body> <script> async function connect() { window.api = await
282+UrbitHttpApi.Urbit.authenticate({ ship: "zod", url: "localhost:8080", code:
283+"lidlut-tabwed-pillex-ridrup", verbose: true }); document.body.innerHTML =
284+"Connected!"; }; </script> </html>
287+`window.api` can then be used for further communications.
291+The various functions you can use in the `Urbit` object are described below.
295+For poking a ship, the `Urbit` class in `http-api` includes a `poke` function.
296+The `poke` function takes six arguments in a object:
298+| Argument | Type | Description | Example |
299+| ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
300+| `app` | `string` | The Gall agent to poke. | `"graph-store"` |
301+| `mark` | `string` | The mark of the data to poke the agent with. | `"graph-update-3"` |
302+| `json` | any JSON | The data to poke the agent with. | `{foo: "bar", baz: 42}` |
303+| `ship` | `string` | The Urbit ID (`@p`) of the ship without the `~`. This may be ommitted if it's already been set for the whole `Urbit` object. | `"sampel-palnet"` |
304+| `onSuccess` | A function. | This is called if the poke succeeded (the ship ack'd the poke). | `someFunction` |
305+| `onError` | A function. | This is called if the poke failed (the ship nack'd the poke). | `anotherFunction` |
309+This example lets you "hi" your ship with a given message, which will be printed
310+in the terminal. It pokes the `hood` agent (the system agent) with a `helm-hi`
311+mark. The `json` argument just contains the message in a string. If for some
312+reason the `hood` agent rejects the poke, "Poke failed!" will be displayed on
316+<html> <head> <script
317+src="https://unpkg.com/@urbit/http-api"></script> <script
318+src="/session.js"></script> </head> <body> <input id="msg"
319+type="text" placeholder="Message for ship" /> <button id="submit"
320+type="button" onClick="doPoke()" >Submit</button> <p id="err"></p>
321+</body> <script> document.getElementById("msg") .addEventListener("keyup",
322+function(event) { if (event.keyCode === 13) {
323+document.getElementById("submit").click(); } }) const api = new
324+UrbitHttpApi.Urbit(""); api.ship = window.ship; function doPoke() { const msg =
325+document.getElementById("msg").value; api.poke({ app: "hood", mark: "helm-hi",
326+json: msg, onSuccess: success, onError: error }); } function success() {
327+document.getElementById("msg").value = "";
328+document.getElementById("err").innerHTML = ""; } function error() {
329+document.getElementById("msg").value = "";
330+document.getElementById("err").innerHTML = "Poke failed!"; } </script>
334+### Subscribe and Unsubscribe {#subscribe}
336+For subscribing to a particular path in an agent, the `Urbit` class in `http-api` includes a `subscribe` function.
337+The `subscribe` function takes six arguments in a object:
339+| Argument | Type | Description | Example |
340+| -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
341+| `app` | `string` | The Gall agent to which you'll subscribe. | `"graph-store"` |
342+| `path` | `string` | The subscription path. | `"/updates"` |
343+| `ship` | `string` | The Urbit ID (`@p`) of the ship without the `~`. This may be ommitted if it's already been set for the whole `Urbit` object. | `"sampel-palnet"` |
344+| `err` | A function. | This is called if the subscription request fails. | `someFunction` |
345+| `event` | A function. | This is the function to handle each update you receive for this subscription. The function's argument is the update's JSON data. | `anotherFunction` |
346+| `quit` | A function. | This is called if you are kicked from the subscription. | `yetAnotherFunction` |
348+The `subscribe` function returns a subscription ID, which is just a number. This
349+ID can be used to unsubscribe down the line.
351+If the subscription request is successful, you'll continue to receive updates
352+until you either unsubscribe or are kicked by the agent. You may subscribe to
353+multiple different agents and subscription paths by calling the `subscribe`
354+function for each one.
356+If you wish to unsubscribe from a particular subscription, the `Urbit` class in
357+`http-api` includes an `unsubscribe` function. This function just takes a single
358+argument: the subscription ID number of an existing subscription. Once
359+unsubscribed, you'll stop receiving updates for the specified subscription.
363+This example will, upon clicking the "Subscribe" button, subscribe to the
364+`/updates` path of the `graph-store` agent, and print the raw JSON of each
365+update it receives. You can test it by doing something like posting a message in
366+a chat. You can also unsubscribe by clicking the "Unsubscribe" button.
369+<html> <head> <script
370+src="https://unpkg.com/@urbit/http-api"></script> <script
371+src="/session.js"></script> </head> <body> <button id="toggle"
372+type="button" onClick="doSub()" >Subscribe</button> <pre
373+id="event"></pre> </body> <script> const api = new
374+UrbitHttpApi.Urbit(""); api.ship = window.ship; const toggle =
375+document.getElementById("toggle"); const event =
376+document.getElementById("event"); function doSub() { window.id = api.subscribe({
377+app: "graph-store", path: "/updates", event: printEvent, quit: doSub, err:
378+subFail }); toggle.innerHTML = "Unsubscribe"; toggle.onclick = doUnsub;
379+event.innerHTML = "Awaiting event"; }; function doUnsub() {
380+api.unsubscribe(window.id); toggle.innerHTML = "Subscribe"; toggle.onclick =
381+doSub; event.innerHTML = "Subscription closed"; }; function printEvent(update) {
382+event.innerHTML = JSON.stringify(update, null, 2); }; function subFail() {
383+event.innerHTML = "Subscription failed!"; }; </script> </html>
388+The `subscribeOnce` function in the `Urbit` class of `http-api` is a variation
389+on the ordinary [`subscribe`](#subscribe) function. Rather than keeping the
390+subscription going and receiving an arbitrary number of updates, instead it
391+waits to receive a single update and then closes the subscription. This is
392+useful if, for example, you send a poke and just want a response to that one
395+The `subscribeOnce` function also takes an optional `timeout` argument, which
396+specifies the number of milliseconds to wait for an update before closing the
397+subscription. If omitted, `subscribeOnce` will wait indefinitely.
399+`subscribeOnce` takes three arguments (these can't be in an object like most
400+other `Urbit` functions):
402+| Argument | Type | Description | Example |
403+| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | --------------- |
404+| `app` | `string` | The Gall agent to which you'll subscribe. | `"graph-store"` |
405+| `path` | `string` | The subscription path. | `"/updates"` |
406+| `timeout` | `number` | The number of milliseconds to wait for an update before closing the subscription. If omitted, it will wait indefinitely. | `5000` |
408+`subscribeOnce` returns a Promise. If successful, the Promise produces the JSON
409+data of the update it received. If it failed due to either timing out or getting
410+kicked from the subscription, it will return an error message of either
411+`"timeout"` or `"quit"`.
415+Here's a variation on the ordinary [subscribe](#subscribe) function. Rather than
416+printing every `graph-store` update it receives, it will instead just print the
417+first one it receives and close the subscription. Additionally, it sets a five
418+second timeout, and prints an error message if it times out.
421+<html> <head> <script
422+src="https://unpkg.com/@urbit/http-api"></script> <script
423+src="/session.js"></script> </head> <body> <button type="button"
424+onClick="doSub()" >Subscribe Once</button> <pre id="event"></pre>
425+</body> <script> const api = new UrbitHttpApi.Urbit(""); api.ship =
426+window.ship; const event = document.getElementById("event"); function doSub() {
427+event.innerHTML = ""; api.subscribeOnce("graph-store","/updates",5000)
428+.then(printEvent, noEvent); }; function printEvent(update) { event.innerHTML =
429+JSON.stringify(update, null, 2); }; function noEvent(error) { event.innerHTML =
430+error; }; </script> </html>
435+To scry agents on the ship, the `Urbit` class in `http-api` includes a `scry` function.
436+The `scry` function takes two arguments in a object:
438+| Argument | Type | Description | Example |
439+| -------- | -------- | ---------------------------------- | --------------- |
440+| `app` | `string` | The agent to scry. | `"graph-store"` |
441+| `path` | `string` | The path to scry, sans the `care`. | `"/keys"` |
443+The `scry` function returns a promise that, if successful, contains the
444+requested data as JSON.
448+Upon pressing the "Scry Graphs" button, this example will scry the `graph-store`
449+agent's `/keys` endpoint for the list of graphs, and print the resulting JSON
453+<html> <head> <script
454+src="https://unpkg.com/@urbit/http-api"></script> <script
455+src="/session.js"></script> </head> <body> <button id="scry"
456+type="button" onClick="doScry()" >Scry Graphs</button> <pre
457+id="result"></pre> </body> <script> const api = new
458+UrbitHttpApi.Urbit(""); api.ship = window.ship; async function doScry() { var
459+groups = await api.scry({app: "graph-store", path: "/keys"});
460+document.getElementById("result") .innerHTML = JSON.stringify(groups, null, 2);
461+} </script> </html>
466+To run a thread, the `Urbit` class in `http-api` includes a `thread` function.
467+The `thread` function takes five arguments in an object:
469+| Argument | Type | Description | Example |
470+| ------------ | -------- | ------------------------------------------------------------------------------------------------------------- | ----------------------- |
471+| `inputMark` | `string` | The mark to convert your JSON data to before giving it to the thread as its argument. | `"graph-view-action"` |
472+| `outputMark` | `string` | The result of the thread should be converted to this mark before being converted to JSON and returned to you. | `"tang"` |
473+| `threadName` | `string` | The name of the thread to run. | `"graph-eval"` |
474+| `body` | any JSON | The data to give to the thread as its argument. | `{foo: "bar", baz: 42}` |
475+| `desk` | `string` | The desk in which the thread resides. This may be ommitted if previously set for the whole `Urbit` object. | `"landscape"` |
477+The `thread` function will produce a promise that, if successful, contains the
478+JSON result of the thread.
482+This example takes a hoon expression (such as `(add 1 1)`), evalutes it with the
483+`graph-eval` thread in the `landscape` desk, and prints the result.
486+<html> <head> <script
487+src="https://unpkg.com/@urbit/http-api"></script> <script
488+src="/session.js"></script> </head> <body> <input id="hoon"
489+type="text" placeholder="Hoon to evaluate" /> <button id="submit"
490+type="button" onClick="runThread()" >Submit</button> <pre
491+id="expr"></pre> <pre id="result"></pre> </body> <script>
492+document.getElementById("hoon") .addEventListener("keyup", function(event) { if
493+(event.keyCode === 13) { document.getElementById("submit").click(); } }); const
494+hoon = document.getElementById("hoon"); const expr =
495+document.getElementById("expr"); const result =
496+document.getElementById("result"); const desk = "landscape"; const api = new
497+UrbitHttpApi.Urbit("", "", desk); api.ship = window.ship; async function
498+runThread() { const threadResult = await api.thread({ inputMark:
499+"graph-view-action", outputMark: "tang", threadName: "graph-eval", body: {eval:
500+hoon.value} }); result.innerHTML = threadResult[0].join("\n"); expr.innerHTML =
501+hoon.value; hoon.value = ""; }; </script> </html>
506+Rather than just closing individual subscriptions, the entire channel can be
507+closed with the `delete` function in the `Urbit` class of `http-api`. The
508+function takes no arguments, and can be called like `api.cancel()` (replacing
509+`api` with whatever you've named the `Urbit` object you previously instantiated).
510+When a channel is closed, all subscriptions will be cancelled and all pending
511+updates will be discarded.
515+An existing instance of `http-api`'s `Urbit` class can be reset with its
516+`reset` function. This function takes no arguments, and can be called like
517+`api.reset()` (replacing `api` with whatever you've named the `Urbit` object you
518+previously instantiated). When called, the channel will be closed and all
519+subscriptions cancelled. Additionally, all outstanding outbound pokes will be
520+discarded and a fresh channel ID will be generated.
524+- [Eyre External API Reference][eyre-ext-ref] - Lower-level documentation of
525+ Eyre's external API.
526+- [Eyre Guide][eyre-guide] - Lower-level examples of using Eyre's external API
528+- [`http-api` on Github][http-api-src] - The source code for `@urbit/http-api`.
529+- [Software Distribution][dist] - This section of documentation explains how to
530+ distribute apps in Urbit, including how to package and serve front-end files.
532+[eyre-ext-ref]: /docs/arvo/eyre/external-api-ref
533+[eyre-guide]: /docs/arvo/eyre/guide
534+[http-api-src]: https://github.com/urbit/urbit/tree/master/pkg/npm/http-api
535+[dist]: /docs/userspace/dist/dist
536+[eyre]: /docs/glossary/eyre
537+[vane]: /docs/glossary/vane
538+[arvo]: /docs/glossary/arvo
539+[hoon]: /docs/glossary/hoon
540+[gall]: /docs/glossary/gall
541+[clay]: /docs/glossary/clay
542+[desk]: /docs/glossary/desk
543+[mark]: /docs/glossary/mark
544+[sse]: https://html.spec.whatwg.org/#server-sent-events
545+[@urbit/http-api]: https://github.com/urbit/urbit/tree/master/pkg/npm/http-api