Eyre is the webserver vane.
HTTP messages come in from outside and Eyre produces HTTP messages in response. In general, apps do not call Eyre; rather, Eyre calls apps. Eyre has a number of ways to handle such HTTP requests which we'll briefly describe.
Most types of requests require the client provide a valid session cookie which is obtained by authenticating with your ship's web login code. Authentication is documented in the Authentication section of the External API Reference documentation.
The Channel System
The channel system is designed to be extremely simple with just a handful of
response JSON objects to deal. Essentially it's a thin layer on top of the underlying Gall agent interface. You can poke agents, subscribe for updates, etc, just like you would from within Urbit.
Detailed documentation of the channel system's JSON API is provided in the External API Reference document with corresponding examples in the Guide document.
Along with the channel system, Eyre also provides a way to make read-only requests for data which are called scries. Eyre's scry interface is separate to the channel system but may be useful in conjunction with it.
Details of Eyre's scry API are in the Scry section of the External API Reference document.
Spider (the Gall agent that manages threads) has an Eyre binding that allows you to run threads through Eyre. Spider's HTTP API is not part of Eyre proper, so is documented separately in the Threads documentation.
Generators, which are like Hoon scripts, can also be used through Eyre. Rather than having a predefined JSON API, they instead handle HTTP requests and return HTTP responses directly, and are therefore a more complex case that you're less likely to use.
Their usage is explained in the %serve section of the Internal API Reference documentation and a practical example is provided in the Generators section of the Guide document.
Direct HTTP Handling With Gall Agents
As well as the Channel System and Scries, it's also possible for Gall agents to deal directly with HTTP requests. This method is much more complicated than the channel system so you're unlikely to use it unless you want to build a custom HTTP-based API or something like that.
This method is explained in the %connect section of the Internal API Reference document and a detailed example is provided in the Agents: Direct HTTP section of the Guide document.
Cross-Origin Resource Sharing
Eyre supports both simple CORS requests and OPTIONS preflight requests. It has a CORS registry with three categories -
requests. Eyre will respond positively for origins in its
approved list and negatively for all others. Eyre will add origins in requests that it doesn't have in either its
rejected lists to its
requests list. Eyre always allows all methods and headers over CORS.
There are three generators -
|cors-reject to view, approve, and deny origins respectively from the dojo. Eyre also has tasks to approve and reject origins programmatically, and a number of scry endpoints to query them. Examples are also included in the Managing CORS Origins section of the Guide document.
External API Reference - Details of Eyre's external API including the channel system's JSON API.
Internal API Reference - The
tasks Eyre takes and the
gifts it returns.
Scry Reference - The scry endpoints of Eyre.
Data Types - Reference documentation of the various data types used by Eyre.
Guide - Practical examples of the different ways of using Eyre.