blob: 99a525e8afed3652f38eb88c67fa5ac023b965d6 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
# Channels and messages
```mermaid
---
Channel lifecycle
---
stateDiagram-v2
[*] --> Active : POST /api/channels
Active --> Deleted : DELETE /api/channels/C1234
Active --> Deleted : Expiry
Deleted --> [*] : Purge
```
```mermaid
---
Message lifecycle
---
stateDiagram-v2
[*] --> Sent : POST /api/channels/C1234
Sent --> Deleted : DELETE /api/messages/Mabcd
Sent --> Deleted : Expiry
Deleted --> [*] : Purge
```
Messages allow logins to communicate with one another. Channels are the conversations to which those messages are sent.
Every channel has a unique name, chosen when the channel is created.
## Expiry and purging
Both channels and messages expire after a time. Messages expire 90 days after being sent. Channels expire 90 days after the last message sent to them, or after creation if no messages are sent in that time.
Deleted channels and messages, including those that have expired, are temporarily retained by the service, to allow clients that are not connected to receive the corresponding deletion [events](./events.md). To limit storage growth, deleted channels and messages are purged from the service seven days after they were deleted.
## `POST /api/channels`
Creates a channel.
### Request
```json
{
"name": "a unique channel name"
}
```
The request must have the following fields:
| Field | Type | Description |
|:-------|:-------|:--|
| `name` | string | The channel's name. |
### Success
This endpoint will respond with a status of `200 Okay` when successful. The body of the response will be a JSON object describing the new channel:
```json
{
"name": "a unique channel name",
"id": "C9876cyyz"
}
```
The response will have the following fields:
| Field | Type | Description |
|:-------|:-------|:--|
| `name` | string | The channel's name. |
| `id` | string | A unique identifier for the channel. This can be used to associate the channel with other events, or to make API calls targeting the channel. |
### Duplicate channel name
This endpoint will respond with a status of `409 Conflict` if a channel with the requested name already exists.
## `POST /api/channels/:id`
Sends a message to a channel.
This endpoint requires the following path parameter:
| Parameter | Type | Description |
|:----------|:-------|:--|
| `id` | string | A channel ID. |
### Request
```json
{
"body": "my amazing thoughts, by bob"
}
```
The request must have the following fields:
| Field | Type | Description |
|:-------|:-------|:--|
| `body` | string | The message to deliver to the channel. |
### Success
This endpoint will respond with a status of `202 Accepted` when successful. The response will not include a body.
### Invalid channel ID
This endpoint will respond with a status of `404 Not Found` if the channel ID is not valid.
## `DELETE /api/channels/:id`
Deletes a channel (and all messages in it).
This endpoint requires the following path parameter:
| Parameter | Type | Description |
|:----------|:-------|:--|
| `id` | string | A channel ID. |
### Success
This endpoint will respond with a status of `202 Accepted` when successful. The response will not include a body.
### Invalid channel ID
This endpoint will respond with a status of `404 Not Found` if the channel ID is not valid.
## `DELETE /api/messages/:id`
Deletes a message.
This endpoint requires the following path parameter:
| Parameter | Type | Description |
|:----------|:-------|:--|
| `id` | string | A message ID. |
### Success
This endpoint will respond with a status of `202 Accepted` when successful. The response will not include a body.
### Invalid message ID
This endpoint will respond with a status of `404 Not Found` if the message ID is not valid.
|
