Activity · 契約參考
HTTP 操作索引
本頁列出契約測試版的 canonical Activity HTTP surface。目前尚未在網站上獨立發佈有版本號的 machine-readable schema。
契約狀態
| 項目 | 目前狀態 |
|---|---|
| OpenAPI version | 3.1.0 |
| API document version | 0.8.0 |
| Customer base path | /api/v1 |
| Maturity | 契約測試版 |
| Public realtime API | 無 |
| 受支援的 SDK | 無 |
核心 schema 與 HMAC model 可供 consumer beta integration 使用。Activity 尚未提供 deprecation window、migration policy、generated client 或 managed-service compatibility promise。
身分驗證與 response
每個 /api/v1 operation 都需要 x-tenant-id、x-actor-id、x-feedaas-timestamp 與 x-feedaas-signature。呼叫以下 operation 前，請先閱讀簽署 Activity 請求。
GET /api/health 是唯一不需身分驗證的 operation。
成功 response 會依資源使用不同 top-level key，例如 post、follow、relationship、like、comment、report 或 ok。Timeline 與 comment collection 使用 data 加上 page.next_cursor。
Error 使用同一種 envelope：
{
"error": {
"code": "post_not_found",
"message": "post not found"
}
}Health
| Method | Path | 用途 |
|---|---|---|
GET | /api/health | 回傳 process 與 service health |
Post 與 timeline
| Method | Path | 用途 |
|---|---|---|
POST | /api/v1/posts | 以簽署 actor 發佈 post |
PATCH | /api/v1/posts/{post_id} | 修改作者擁有的 body、metadata 或 render reference |
DELETE | /api/v1/posts/{post_id} | Soft delete 作者擁有的 post，並移除 timeline entry |
GET | /api/v1/timeline/home | 讀取簽署 actor 的 materialized home timeline |
GET | /api/v1/actors/{actor_id}/posts | 讀取簽署 actor 可見的 profile post |
Publish 接受選填的 idempotency_key。在同一個 tenant 與 actor 範圍內重複使用相同 key，會回傳原本的 post，不會重複執行 projection 或 delivery work。Timeline 與 profile read 使用 opaque cursor pagination。整合前請閱讀發佈與讀取、排序與重建及可見性與政策。
Follow graph 與 relationship
| Method | Path | 用途 |
|---|---|---|
POST | /api/v1/follows | Follow followed_id 或重新啟用 relationship |
DELETE | /api/v1/follows/{followed_id} | Unfollow 並清除既有 following entry |
POST | /api/v1/relationships/{actor_id}/mute | Mute actor，並從 caller read 移除其 entry |
DELETE | /api/v1/relationships/{actor_id}/mute | 把 relationship state 還原成 active |
POST | /api/v1/relationships/{actor_id}/block | 套用雙向 read 與 follow 限制 |
DELETE | /api/v1/relationships/{actor_id}/block | 刪除 caller 的 block edge |
這些 operation 實作 feed graph state，不取代 host business authorization 或 organization membership。
Like、comment 與 reply
| Method | Path | 用途 |
|---|---|---|
POST | /api/v1/posts/{post_id}/likes | 冪等記錄簽署 actor 的 like |
DELETE | /api/v1/posts/{post_id}/likes | 移除簽署 actor 的 like，或確認已不存在 |
GET | /api/v1/posts/{post_id}/comments | 使用 cursor 列出 top-level comment 或 reply |
POST | /api/v1/posts/{post_id}/comments | 建立 top-level comment |
PATCH | /api/v1/posts/{post_id}/comments/{comment_id} | 修改作者擁有的 comment |
DELETE | /api/v1/posts/{post_id}/comments/{comment_id} | Soft delete 作者擁有的 comment 與可見 reply subtree |
POST | /api/v1/posts/{post_id}/comments/{comment_id}/replies | 回覆既有 comment |
刪除 top-level comment 後，其 reply subtree 也會從 comment read 與 derived counter 移除。Comment body 與 metadata 仍是 Activity boundary 內的 host-shaped content。
Repost 與 share
| Method | Path | 用途 |
|---|---|---|
POST | /api/v1/posts/{post_id}/reposts | 建立 first-class shared post 與 repost engagement |
POST | /api/v1/posts/{post_id}/shares | 建立可帶 body 與 render reference 的 shared post |
Share attribution 與 nested rendering rule 仍在 hardening。render_refs 只儲存 host reference，不會解析 identity 或驗證 media byte。
Viewer lifecycle
| Method | Path | 用途 |
|---|---|---|
POST | /api/v1/posts/{post_id}/hide | 對簽署 viewer 隱藏可見 post |
POST | /api/v1/posts/{post_id}/reports | 建立或更新簽署 actor 的 report record |
Hide 不會刪除來源 post。Report 不會做 moderation decision，也不會改變 moderation_state。
常見 domain error
| Status | Code |
|---|---|
400 | missing_tenant_id、invalid_tenant_id、invalid_followed_id、cannot_follow_self、invalid_actor_id、invalid_cursor 與 comment validation error |
401 | HMAC timestamp 或 signature 缺少、格式錯誤、過期或不相符 |
403 | not_post_author、not_comment_author、relationship_blocked |
404 | post_not_found、comment_not_found |
422 | Ash 或未分類的 domain validation error |
無權讀取的 post 會回傳 post_not_found。不要用 error 探測 cross-tenant、hidden、private、muted 或 blocked resource。
Compatibility boundary
OpenAPI artifact 是 operation-level source of truth。契約測試期間，client 應保持 cursor opaque、不依賴未記載欄位，也不要在未檢查目前 artifact 的情況下重新產生 client。
/api/v1 prefix 不代表 generally available stable API。目前沒有公開的 deprecation overlap window、changelog contract、migration guide 或 server-to-client compatibility matrix。