git.iko.soy/urbit.org
on 4fdc19d help sign in
urbit.org/content/docs/userspace/threads/http-api.md
73 lines 3.4 kB history raw
1+++
2title = "HTTP API"
3weight = 2
4template = "doc.html"
5+++
7Spider has an Eyre binding which allows threads to be run externally via [authenticated](/docs/arvo/eyre/external-api-ref#authentication) HTTP POST requests.
9Spider is bound to the `/spider` URL path, and expects the requested URL to look like:
11```
12http{s}://{host}/spider/{desk}/{inputMark}/{threadName}/{outputMark}
13```
15The `desk` is the desk in which the thread resides. The `inputMark` is the `mark` the thread takes. The `threadName` is the name of the thread, e.g. `foo` for `/ted/foo/hoon`. The `outputMark` is the `mark` the thread produces. You may also include a file extension though it doesn't have an effect.
17When Spider receives an HTTP request, the following steps happen:
191. It converts the raw body of the message to `json` using `de-json:html`
202. It creates a `tube:clay` (`mark` conversion gate) from `json` to whatever input `mark` you've specified and does the conversion.
213. It runs the specified thread and provides a `vase` of `(unit inputMark)` as the argument.
224. The thread does its thing and finally produces its result as a `vase` of `outputMark`.
235. Spider creates another `tube:clay` from the output `mark` to `json` and converts it.
246. It converts the `json` back into raw data suitable for the HTTP response body using `en-json:html`.
257. Finally, it composes the HTTP response and passes it back to Eyre which passes it on to the client.
27Thus, it's important to understand that the original HTTP request and final HTTP response must contain JSON data, and therefore the input & output `mark`s you specify must each have a `mark` file in `/mar` that includes a conversion method for `json -> inputMark` and `outputMark -> json` respectively.
29## Example
31Here we'll look at running Spider threads through Eyre.
33Here's an extremely simple thread that takes a `vase` of `(unit json)` and just returns the `json` in a new `vase`. You can save it in `/ted` and `|commit %base`:
35`eyre-thread.hoon`
37```hoon
38/- spider
39=, strand=strand:spider
40^- thread:spider
41|= arg=vase
42=/ m (strand ,vase)
43^- form:m
44=/ =json
45 (need !<((unit json) arg))
46(pure:m !>(json))
47```
49First we must obtain a session cookie by [authenticating](/docs/arvo/eyre/guide#authenticating).
51Now we can try and run our thread. Spider is bound to the `/spider` URL path, and expects the rest of the path to be `/{desk}/{inputMark}/{thread}/{outputMark}`. Our `{thread}` is called `eyre-thread` and is in the `%base` `{desk}`. Both its `{inputMark}` and `{outputMark}` are `json`. Therefore, our URL path will be `/spider/base/json/eyre-agent/json`. Our request will be an HTTP POST request and the body will be some `json`, in this case `[{"foo": "bar"}]`:
53```
54curl -i --header "Content-Type: application/json" \
55 --cookie "urbauth-~zod=0v6.h6t4q.2tkui.oeaqu.nihh9.i0qv6" \
56 --request POST \
57 --data '[{"foo": "bar"}]' \
58 http://localhost:8080/spider/base/json/eyre-thread/json
59```
61Spider will run the thread and the result will be returned through Eyre in the body of an HTTP response with a 200 status code:
63```
64HTTP/1.1 200 ok
65Date: Sun, 06 Jun 2021 05:32:45 GMT
66Connection: keep-alive
67Server: urbit/vere-1.5
68set-cookie: urbauth-~zod=0v6.h6t4q.2tkui.oeaqu.nihh9.i0qv6; Path=/; Max-Age=604800
69content-type: application/json
70transfer-encoding: chunked
72[{"foo":"bar"}]
73```