Okay/Spec: Difference between revisions
No edit summary |
No edit summary |
||
| Line 5: | Line 5: | ||
== in summary == | == in summary == | ||
Okay is a group chat protocol. You | Okay is a group chat protocol. You connect to "Spaces" which contain “Rooms” which contain “People” who “Talk” by sending and receiving “Messages” to and from the “Server”. | ||
* A room is just a special URI which you can POST messages to and GET them back from at a later date. | * A room is just a special URI which you can POST messages to and GET them back from at a later date. | ||
* You can use WebSockets to get a real-time feed of events that you’re interested in. | * You can use WebSockets to get a real-time feed of events that you’re interested in. | ||
* | * Pretty much everything is represented as HTML over the wire. This allows most client implementations skip the bit where they convert every message into HTML, while providing a stable format for non-web platforms to convert into their own inferior representations. This also has other benefits, such as allowing users to browse most spaces with just their web browser, and letting you do really really stupid things with your messages. | ||
* | * Authentication works by just signing every request with a key that gets generated by the client on first use. | ||
== conventions == | == conventions == | ||
| Line 21: | Line 21: | ||
* what do we do about invalid html | * what do we do about invalid html | ||
== | == connections == | ||
Connections in Okay generally happen over HTTPS (preferred) or HTTP (TODO: elaborate). | |||
A typical connection to an never before seen space usually goes like this: | A typical connection to an never before seen space usually goes like this: | ||
| Line 27: | Line 28: | ||
* The user hands the client a URI to examine; | * The user hands the client a URI to examine; | ||
* The client issues a GET request to the URI and examines the response; | * The client issues a GET request to the URI and examines the response; | ||
* If the response meets all the [[Okay#discovery|discovery requirements]], it generates a new | * If the response meets all the [[Okay#discovery|discovery requirements]], it generates a new key pair and registers itself with the space’s registration endpoint; | ||
* Once everyone’s happy, the client can begin posting messages to rooms. | * Once everyone’s happy, the client can begin posting messages to rooms. | ||
== spaces == | == spaces == | ||
Conceptually, a '''space''' is an isolated container that stores room state and user data. They are each represented by a [[Okay#ok-space|HTML element]] which provides URIs for clients to send their requests to (for example, its [[Okay#rooms|room directory]] or [[Okay#initiation|registration page]]). The URI of the document that contains this is called the space's '''root URI'''. | |||
=== discovery === | === discovery === | ||
| Line 61: | Line 62: | ||
A list of valid anchor <code>rel</code> attributes and their purposes is described below: | A list of valid anchor <code>rel</code> attributes and their purposes is described below: | ||
'''Key''': <span class="required">◈ ''' | '''Key''': <span class="required">◈ '''required'''</span>, <span class="optional>◇ '''optional'''</span>, <span class="multiple">❖ '''can be specified multiple times''' | ||
{| class="wikitable" | {| class="wikitable" | ||
|+ | |+ | ||
| Line 77: | Line 78: | ||
|} | |} | ||
==== linking to other spaces ==== | ==== linking to other spaces ==== | ||
== initiation == | == initiation == | ||
A client must register itself with a space before it can send messages to rooms. | A client must register itself with a space before it can send messages to rooms. | ||
=== keys === | |||
When registering with a space, a client should transparently generate a key pair (TODO: what type(s)?) and store it for use in subsequent requests. | |||
=== registration the page === | |||
The registration page allows clients to register their public key and [[Okay#profiles|profile]] with the space. | |||
== the directory == | == the directory == | ||