@@ -0,0 +1,74 @@
1++++
2+title = "HTTP API"
3+weight = 2
4+template = "doc.html"
5++++
6+
7+Spider has an Eyre binding which allows threads to be run externally via [authenticated](@/docs/arvo/eyre/external-api-ref.md#authentication) HTTP POST requests.
8+
9+Spider is bound to the `/spider` URL path, and expects the requested URL to look like:
10+
11+```
12+http{s}://{host}/spider/{inputMark}/{threadName}/{outputMark}
13+```
14+
15+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.
16+
17+When Spider receives an HTTP request, the following steps happen:
18+
19+1. It converts the raw body of the message to `json` using `de-json:html`
20+2. It creates a `tube:clay` (`mark` conversion gate) from `json` to whatever input `mark` you've specified and does the conversion.
21+3. It runs the specified thread and provides a `vase` of `(unit inputMark)` as the argument.
22+4. The thread does its thing and finally produces its result as a `vase` of `outputMark`.
23+5. Spider creates another `tube:clay` from the output `mark` to `json` and converts it.
24+6. It converts the `json` back into raw data suitable for the HTTP response body using `en-json:html`.
25+7. Finally, it composes the HTTP response and passes it back to Eyre which passes it on to the client.
26+
27+Thus, 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.
28+
29+
30+# Example
31+
32+Here we'll look at running Spider threads through Eyre.
33+
34+Here'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 %home`:
35+
36+`eyre-thread.hoon`
37+
38+```hoon
39+/- spider
40+=, strand=strand:spider
41+^- thread:spider
42+|= arg=vase
43+=/ m (strand ,vase)
44+^- form:m
45+=/ =json
46+ (need !<((unit json) arg))
47+(pure:m !>(json))
48+```
49+
50+First we must obtain a session cookie by [authenticating](@/docs/arvo/eyre/examples.md#authenticating).
51+
52+Now we can try and run our thread. Spider is bound to the `/spider` URL path, and expects the rest of the path to be `/{inputMark}/{thread}/{outputMark}`. Our `{thread}` is called `eyre-thread`, and both its `{inputMark}` and `{outputMark}` are `json`, so our URL path will be `/spider/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+
54+```
55+curl -i --header "Content-Type: application/json" \
56+ --cookie "urbauth-~zod=0v6.h6t4q.2tkui.oeaqu.nihh9.i0qv6" \
57+ --request POST \
58+ --data '[{"foo": "bar"}]' \
59+ http://localhost:8080/spider/json/eyre-thread/json
60+```
61+
62+Spider 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+
64+```
65+HTTP/1.1 200 ok
66+Date: Sun, 06 Jun 2021 05:32:45 GMT
67+Connection: keep-alive
68+Server: urbit/vere-1.5
69+set-cookie: urbauth-~zod=0v6.h6t4q.2tkui.oeaqu.nihh9.i0qv6; Path=/; Max-Age=604800
70+content-type: application/json
71+transfer-encoding: chunked
72+
73+[{"foo":"bar"}]
74+```