feat: initial commit
Axum/Postgres server with auth, migrations, and Docker setup.
This commit is contained in:
230
docs/api.md
Normal file
230
docs/api.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# API Reference
|
||||
|
||||
Base URL: `http://localhost:3000/api/v1`
|
||||
|
||||
---
|
||||
|
||||
## Users
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/users` | List all users |
|
||||
| POST | `/users` | Create a user |
|
||||
| GET | `/users/{id}` | Get a user |
|
||||
| PUT | `/users/{id}` | Update a user (display_name, avatar_url, bio) |
|
||||
| DELETE | `/users/{id}` | Soft-delete a user |
|
||||
|
||||
**POST /users — body**
|
||||
```json
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password_hash": "...",
|
||||
"username": "jane",
|
||||
"display_name": "Jane",
|
||||
"avatar_url": null,
|
||||
"bio": null,
|
||||
"email_verified": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Auth Tokens
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/users/{id}/auth-tokens` | List tokens for a user |
|
||||
| POST | `/auth-tokens` | Create a token |
|
||||
| DELETE | `/auth-tokens/{id}` | Revoke a token |
|
||||
|
||||
**POST /auth-tokens — body**
|
||||
```json
|
||||
{
|
||||
"user_id": "uuid",
|
||||
"kind": "refresh_token",
|
||||
"expires_at": "2026-09-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
`kind`: `password_reset` | `email_verification` | `refresh_token`
|
||||
|
||||
**POST /auth-tokens — response** includes `token` (raw value) and `record`.
|
||||
|
||||
---
|
||||
|
||||
## Workspaces
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/workspaces` | List all workspaces |
|
||||
| POST | `/workspaces` | Create a workspace |
|
||||
| GET | `/workspaces/{id}` | Get a workspace |
|
||||
| PUT | `/workspaces/{id}` | Update a workspace (name, slug) |
|
||||
| DELETE | `/workspaces/{id}` | Soft-delete a workspace |
|
||||
|
||||
**POST /workspaces — body**
|
||||
```json
|
||||
{
|
||||
"name": "Acme",
|
||||
"slug": "acme",
|
||||
"owner_id": "uuid"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workspace Members
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/workspaces/{id}/members` | List members |
|
||||
| POST | `/workspaces/{id}/members` | Add a member |
|
||||
| PUT | `/workspaces/{workspace_id}/members/{user_id}` | Update role / display name |
|
||||
| DELETE | `/workspaces/{workspace_id}/members/{user_id}` | Remove a member |
|
||||
|
||||
**POST body**
|
||||
```json
|
||||
{
|
||||
"user_id": "uuid",
|
||||
"role": "member",
|
||||
"display_name": null,
|
||||
"avatar_url": null
|
||||
}
|
||||
```
|
||||
`role`: `owner` | `admin` | `member`
|
||||
|
||||
---
|
||||
|
||||
## Workspace Invitations
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/workspaces/{id}/invitations` | List invitations |
|
||||
| POST | `/workspaces/{id}/invitations` | Create an invitation |
|
||||
| DELETE | `/invitations/{id}` | Delete an invitation |
|
||||
|
||||
**POST body**
|
||||
```json
|
||||
{
|
||||
"created_by": "uuid",
|
||||
"max_uses": 10,
|
||||
"expires_at": "2026-09-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
`max_uses` and `expires_at` are optional. The invite `token` is generated server-side.
|
||||
|
||||
---
|
||||
|
||||
## Conversations
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/conversations` | List conversations (`?workspace_id=uuid`) |
|
||||
| POST | `/conversations` | Create a conversation |
|
||||
| GET | `/conversations/{id}` | Get a conversation |
|
||||
| PUT | `/conversations/{id}` | Update a conversation (name, is_public) |
|
||||
| DELETE | `/conversations/{id}` | Soft-delete a conversation |
|
||||
|
||||
**POST body**
|
||||
```json
|
||||
{
|
||||
"workspace_id": "uuid",
|
||||
"kind": "channel",
|
||||
"name": "general",
|
||||
"is_public": true,
|
||||
"created_by": "uuid"
|
||||
}
|
||||
```
|
||||
`kind`: `dm` | `group` | `channel`
|
||||
`workspace_id` is optional (null for DMs).
|
||||
|
||||
---
|
||||
|
||||
## Conversation Members
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/conversations/{id}/members` | List members |
|
||||
| POST | `/conversations/{id}/members` | Add a member |
|
||||
| DELETE | `/conversations/{conversation_id}/members/{user_id}` | Remove a member |
|
||||
|
||||
**POST body**
|
||||
```json
|
||||
{
|
||||
"user_id": "uuid"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Messages
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/conversations/{id}/messages` | List messages (chronological) |
|
||||
| POST | `/messages` | Send a message |
|
||||
| GET | `/messages/{id}` | Get a message |
|
||||
| PUT | `/messages/{id}` | Edit a message (content) |
|
||||
| DELETE | `/messages/{id}` | Soft-delete a message |
|
||||
|
||||
**POST body**
|
||||
```json
|
||||
{
|
||||
"conversation_id": "uuid",
|
||||
"user_id": "uuid",
|
||||
"content": "Hello!"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Attachments
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/messages/{id}/attachments` | List attachments for a message |
|
||||
| POST | `/attachments` | Create an attachment |
|
||||
| DELETE | `/attachments/{id}` | Delete an attachment |
|
||||
|
||||
**POST body**
|
||||
```json
|
||||
{
|
||||
"message_id": "uuid",
|
||||
"url": "https://...",
|
||||
"filename": "file.pdf",
|
||||
"mime_type": "application/pdf",
|
||||
"size_bytes": 102400
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reactions
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/messages/{id}/reactions` | List reactions for a message |
|
||||
| POST | `/reactions` | Add a reaction |
|
||||
| DELETE | `/reactions/{id}` | Remove a reaction |
|
||||
|
||||
**POST body**
|
||||
```json
|
||||
{
|
||||
"message_id": "uuid",
|
||||
"user_id": "uuid",
|
||||
"emoji": "👍"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Response conventions
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| 200 | OK |
|
||||
| 201 | Created |
|
||||
| 204 | Deleted (no body) |
|
||||
| 404 | Not found |
|
||||
| 500 | Internal server error (body: error string) |
|
||||
|
||||
Soft-deleted resources (`users`, `workspaces`, `conversations`, `messages`) are excluded from all list/get responses.
|
||||
Reference in New Issue
Block a user