WARNING: This document is Work in Progress. It assumes the reader has prior good knowledge of the Matrix C2S API on which this document is based, until all sections are filled. Some info is also left generic/incomplete and one should assume the Matrix endpoints are just ported as-is except for the API Baseline directives. In doubt, follow the Matrix spirit.
WARNING: This API is currently very volatile and considered bleeding edge. Reviews and comments are welcome and encouraged as long as they keep in mind the purposeful lack of information on some topics/endpoints in the short-term.
The following RFCs are prerequisites to this document:
- 2119 - Key words for use in RFCs to Indicate Requirement Levels
- 2606 - Reserved Top Level DNS Names
- 8174 - Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
The following spec documents are prerequisites to this document:
This document describes the API that can be used in the scope of data exchanges between a client and a server.
All the endpoints MUST be prefixed with /data/client.
Via .well-known at /.well-known/grid/client
With format:
{
"v": "0",
"g.data": [
{
"base_url": "https://example.org" # Top domain style
}
{
"base_url": "https://grid.example.org/data" # Sub domain style
}
]
}Top level keys define the entry.
Official keys start with g.
Custom keys must use Java package naming convention
g.data is an array of objects containing the following key(s):
| Key | Purpose |
|---|---|
base_url |
Mandatory. Base URL to the API without trailing / |
Clients need to try to use them in order until one server reply. Caching of data is controlled via regular HTTP headers, but should not be cached between client restarts.
Credentials: MAY
Get the support version of the API from the server.
Status: 200
Body:
{
"api": [
"v0",
"arbitrary.version.v34032"
],
"server": {
"name": "Awesome-Grid-Data-Server-Implementation",
"version": "v0.0.1-WE_ARE_SUPER_ALPHA"
}
}Credentials: MAY
Check if the v0 API is available. MAY act as a ping to the server.
Status: 200
Body:
{}Access to endpoints MAY be restricted by the use of credentials from the client to the server.
TBC
Credentials: SHOULD
TBC - Assume like Matrix with naming changes
Credentials: SHOULD
Create a new channel and return its ID.
Status: 200
Body:
{
"id": "#abcdefgABCDEF"
}Status 401 is credentials are mandatory
TBC with body
Status 403 if creating a channel is not allowed
TBC with body
Credentials: MAY
Get the most recent N events in Timeline order in a simple client format. This can be used for peeking or to see the timeline without credentials.
Note: Timeline order is defined in the Base specification.
TODO: Define paging: Assume Matrix-style for now.
If success:
Status: 200
Body:
{
"events": [
{
"v": "0.0",
"type:" "g.c.create",
"...": "..."
},
{
"v": "0.0",
"type": "g.c.member",
"sender": "@senderUserID",
"scope": "@invteeUserID"
"content": {
"membership": "join"
}
},
{
"v": "0.0",
"type": "g.c.message",
"...": "...",
"content": {
"body": {
"text/plain": "Blah in plain text",
"text/html", "<h1>Blah</h1>In HTML super quality"
}
}
}
]
}NOTE: Just an example, non-normative
Credentials: SHOULD
Send an event to a room in timeline mode (do DAG linking on server-side).
The {txnId} path parameter is used to de-duplicate requests in case of network issues.
Body:
{
"type": "g.c.message",
"content": {
"body": {
"text/plain": "Just a simple text message",
"text/html": "I am a fancy <b>HTML<b> view of a simple text message"
}
}
}State event can be sent by setting a scope key.
If success:
Status: 200
Body:
{
"id": "$aldksfo34324543"
}Get the most recent N state events in Timeline order in a simple client format.
Get the event DAG latest info (like extremities)
Send a new event in full format with all the required fields. The server SHOULD NOT change anything on the event.
Get the state DAG latest info (like extremities).
This and any /do/ paths are convenience endpoint for clients that map to predefined events. The same action can be performed by sending plain events to the channel.
Note: These endpoints are meant to be used by "dummy" clients who cannot necessarily perform all required checks and are meant to make it easy for them by having the server perform any prerequisite action(s) for them, if such prerequisite action(s) is possible.
Note: This is just an idea and at this point to be discussed. They are not mandatory in PoC implementations.
This specific endpoint can be used to retrieve the list of possible actions.
Body:
{
"do": [
{
"path": "join",
"description": "Join the room"
},
{
"path": "kick",
"description": "Kick a joined member from the room"
},
"..."
]
}NOTE: Unsubscribing is done using
/leave.
NOTE: Can also be used for kicks, as kick is performing
leaveon another user.
NOTE: Unban is done using
/leave.