Include docs directly (wikis don't carry across forks)
This commit is contained in:
parent
421d5f0c94
commit
d5d618e3ab
|
@ -0,0 +1,15 @@
|
||||||
|
With the server running in the background (e.g. using systemd), you can run the following commands to perform various operations:
|
||||||
|
|
||||||
|
| Command | Effect |
|
||||||
|
| --------------------------------------- |:---------------------------------:|
|
||||||
|
| `--add-room room_id room_name` | to add a room |
|
||||||
|
| `--delete-room room_id` | to delete a room |
|
||||||
|
| `--add-moderator public_key room_id` | to add a moderator to a room |
|
||||||
|
| `--delete-moderator public_key room_id` | to delete a moderator from a room |
|
||||||
|
| `--print-url` | to print your server's URL |
|
||||||
|
|
||||||
|
The open group server binary is normally located in `/usr/bin`, so to e.g. execute the `--print-url` command you'd run:
|
||||||
|
|
||||||
|
```
|
||||||
|
/usr/bin/session-open-group-server --print-url
|
||||||
|
```
|
|
@ -0,0 +1,448 @@
|
||||||
|
All endpoints return the status code in the response body because that's the only way to propagate the status code back to the client when using onion requests.
|
||||||
|
|
||||||
|
## Endpoints
|
||||||
|
|
||||||
|
### GET /rooms/:room_id
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | No | |
|
||||||
|
| Room | No | |
|
||||||
|
|
||||||
|
Returns information about the room with the given ID.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16,
|
||||||
|
room: {
|
||||||
|
id: String,
|
||||||
|
name: String
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /rooms
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | No | |
|
||||||
|
| Room | No | |
|
||||||
|
|
||||||
|
Returns a list of all rooms on the server.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16,
|
||||||
|
rooms: [
|
||||||
|
{
|
||||||
|
id: String,
|
||||||
|
name: String
|
||||||
|
},
|
||||||
|
...
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /files
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | Yes | Basic |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Store a file on the server.
|
||||||
|
|
||||||
|
**Expected body:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
file: String // base64 encoded data
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /rooms/:room_id/image
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | --------- |
|
||||||
|
| Authorization | Yes | Moderator |
|
||||||
|
| Room | No | |
|
||||||
|
|
||||||
|
Set the image for a room.
|
||||||
|
|
||||||
|
**Expected body:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
file: String // base64 encoded data
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16,
|
||||||
|
room_id: String
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /files/:file_id
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | Yes | Basic |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Get a file from the server.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16,
|
||||||
|
result: String // base64 encoded data
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /rooms/:room_id/image
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | No | |
|
||||||
|
| Room | No | |
|
||||||
|
|
||||||
|
Returns the preview image for the given group.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16,
|
||||||
|
result: String // base64 encoded data
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /auth_token_challenge?public_key=string
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | No | |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Get an auth token challenge. The requesting user generates a symmetric key from the ephemeral public key returned by the server and their private key, which can be used to decrypt the ciphertext and get the auth token.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16,
|
||||||
|
challenge: {
|
||||||
|
ciphertext: String, // base64 encoded data
|
||||||
|
ephemeral_public_key: String // base64 encoded data
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /claim_auth_token
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | Yes | Basic |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Claim the auth token in the `Authorization` header.
|
||||||
|
|
||||||
|
**Expected body:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
public_key: String
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### DELETE /auth_token
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | Yes | Basic |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Delete the auth token in the `Authorization` header.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /compact_poll
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | -------------------------------------------------------------------- |
|
||||||
|
| Authorization | No | Authorization is handled on a room-by-room basis in the request body |
|
||||||
|
| Room | No | |
|
||||||
|
|
||||||
|
Poll for new messages, new deletions and the current moderator list for multiple rooms all in one request.
|
||||||
|
|
||||||
|
**Expected body:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
requests: [
|
||||||
|
{
|
||||||
|
room_id: String,
|
||||||
|
auth_token: String,
|
||||||
|
from_deletion_server_id: Option<i64>,
|
||||||
|
from_message_server_id: Option<i64>
|
||||||
|
},
|
||||||
|
{
|
||||||
|
...
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16
|
||||||
|
results: [
|
||||||
|
{
|
||||||
|
room_id: String,
|
||||||
|
status_code: u16,
|
||||||
|
deletions: [ 0, 1, 2, ... ]
|
||||||
|
messages: [
|
||||||
|
{
|
||||||
|
server_id: i64,
|
||||||
|
public_key: String,
|
||||||
|
timestamp: i64,
|
||||||
|
data: String,
|
||||||
|
signature: String
|
||||||
|
},
|
||||||
|
{
|
||||||
|
...
|
||||||
|
}
|
||||||
|
]
|
||||||
|
moderators: [ "public_key_0", "public_key_1", "public_key_2", ... ]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
...
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /messages
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | Yes | Basic |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Store the given message on the server.
|
||||||
|
|
||||||
|
**Expected body:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
public_key: Option<String>, // the public key of the sender
|
||||||
|
timestamp: i64, // the sent timestamp of the message
|
||||||
|
data: String, // the serialized protobuf
|
||||||
|
signature: String // the base64 encoded message signature
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16
|
||||||
|
message: {
|
||||||
|
server_id: String,
|
||||||
|
public_key: Option<String>
|
||||||
|
timestamp: i64
|
||||||
|
data: String
|
||||||
|
signature: String
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /messages?from_server_id=i64&limit=u16
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | Yes | Basic |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Get messages from the server. If `from_server_id` is set only messages stored after that server ID are returned (limited to a maximum of 256 messages). Otherwise, if `limit` is set, the last `limit` messages stored on the server are returned (limited to a maximum of 256 messages).
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16,
|
||||||
|
messages: [
|
||||||
|
{
|
||||||
|
server_id: String,
|
||||||
|
public_key: Option<String>, // the public key of the sender
|
||||||
|
timestamp: i64, // the sent timestamp of the message
|
||||||
|
data: String, // the serialized protobuf
|
||||||
|
signature: String // the base64 encoded message signature
|
||||||
|
},
|
||||||
|
...
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### DELETE /messages/:message_id
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ------------------ |
|
||||||
|
| Authorization | Yes | Basic OR Moderator |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Delete the message with the given ID from the server. The requesting user must either be the sender of the message or have moderation permission.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /deleted_messages?from_server_id=i64&limit=u16
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | Yes | Basic |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Get deleted messages from the server. If `from_server_id` is set only deletions that happened after that server ID are returned (limited to a maximum of 256 deletions). Otherwise, if `limit` is set, the last `limit` deletions stored on the server are returned (limited to a maximum of 256 deletions).
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16,
|
||||||
|
ids: [ 0, 1, 2, ... ] // the server IDs of the deleted messages
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /moderators
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | Yes | Basic |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Get the full list of moderators.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16,
|
||||||
|
moderators: [ "public_key_0", "public_key_1", "public_key_2", ... ]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /block_list
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | --------- |
|
||||||
|
| Authorization | Yes | Moderator |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Ban the given public key from the server.
|
||||||
|
|
||||||
|
**Expected body:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
public_key: String
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### DELETE /block_list/:public_key
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | --------- |
|
||||||
|
| Authorization | Yes | Moderator |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Unban the given public key from the server.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /block_list
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | Yes | Basic |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Get the full list of banned public_keys.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16,
|
||||||
|
moderators: [ "public_key_0", "public_key_1", "public_key_2", ... ]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /member_count
|
||||||
|
|
||||||
|
| Header | Required | Notes |
|
||||||
|
| ------------- | -------- | ----- |
|
||||||
|
| Authorization | Yes | Basic |
|
||||||
|
| Room | Yes | |
|
||||||
|
|
||||||
|
Get the member count for the given room.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
status_code: u16,
|
||||||
|
member_count: usize
|
||||||
|
}
|
||||||
|
```
|
Loading…
Reference in New Issue