From 9c8ac79d0a765c7ae04ac29721e0aad2f78b8ec8 Mon Sep 17 00:00:00 2001 From: Tatsuto YAMAMOTO Date: Thu, 29 Aug 2024 21:56:06 +0900 Subject: [PATCH 1/6] feat: notification apis specification --- src/endpoint/notification.md | 268 +++++++++++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 src/endpoint/notification.md diff --git a/src/endpoint/notification.md b/src/endpoint/notification.md new file mode 100644 index 0000000..96f5c28 --- /dev/null +++ b/src/endpoint/notification.md @@ -0,0 +1,268 @@ +# 通知API + +#### お知らせ（Announce)の種類 + +| 種類コード | 説明 | +| :--------: | :------------------: | +| `info` | 一般的なお知らせ | +| `warn` | ユーザー全体への警告 | + +#### 通知の種類 / `actor`の種類 + +通知の種類 + +##### `followed` - フォローされた + +取り得る`actor`の種類: + +- `account` + +```jsonc +{ + "id": "20923084093774", + "type": "followed", + "actor": { + "type": "account", + "account": { + "id": "209384", + "name": "@johndoe@example.com", + "nickname": "John Doe🌤", + "avatar": "https://cdn.example.com/johndoe/avater" + } + }, + "createdAt": "2024-08-01T00:00:00.000Z" +} +``` + +##### `followRequested` - フォローをリクエストされた + +取り得る`actor`の種類: + +- `account` + +```jsonc +{ + "id": "20923084093774", + "type": "followRequested", + "actor": { + "type": "account", + "account": { + "id": "209384", + "name": "@johndoe@example.com", + "nickname": "John Doe🌤", + "avatar": "https://cdn.example.com/johndoe/avater" + } + }, + "createdAt": "2024-08-01T00:00:00.000Z" +} +``` + +##### `followAccepted` - (自分が行った)フォローが承認された + +取り得る`actor`の種類: + +- `account` + +```jsonc +{ + "id": "20923084093774", + "type": "followAccepted", + "actor": { + "type": "account", + "account": { + "id": "209384", + "name": "@johndoe@example.com", + "nickname": "John Doe🌤", + "avatar": "https://cdn.example.com/johndoe/avater" + } + }, + "createdAt": "2024-08-01T00:00:00.000Z" +} +``` + +##### `mentioned` - メンションされた + +取り得る`actor`の種類: + +- `account` + +```jsonc +{ + "id": "20923084093774", + "type": "mentioned", + // 言及元ノートID + "noteId": "29847304533478", + "actor": { + "type": "account", + "account": { + "id": "209384", + "name": "@johndoe@example.com", + "nickname": "John Doe🌤", + "avatar": "https://cdn.example.com/johndoe/avater" + } + }, + "createdAt": "2024-08-01T00:00:00.000Z" +} +``` + +##### `renoted` - リノートされた + +取り得る`actor`の種類: + +- `account` + +```jsonc +{ + "id": "20923084093774", + "type": "renoted", + // リノートされたノートID + "noteId": "1032809844545437574", + // 投稿本文(CW指定の場合は空になる) + "content": "", + "actor": { + "type": "account", + "account": { + "id": "209384", + "name": "@johndoe@example.com", + "nickname": "John Doe🌤", + "avatar": "https://cdn.example.com/johndoe/avater" + } + }, + "createdAt": "2024-08-01T00:00:00.000Z" +} +``` + +##### `reacted` - リアクションされた + +取り得る`actor`の種類: + +- `account` + +```jsonc +{ + "id": "20923084093774", + "type": "reacted", + // リアクションされたノートのID + "noteId": "3094320840856", + // リアクションの内容 + "content": "🐭", + "actor": { + "type": "account", + "account": { + "id": "209384", + "name": "@johndoe@example.com", + "nickname": "John Doe🌤", + "avatar": "https://cdn.example.com/johndoe/avater" + } + }, + "createdAt": "2024-08-01T00:00:00.000Z" +} +``` + +##### `actor`について + +通知を発生させた主体の種類 + +- `account`: (内部外部問わず) (ユーザー)アカウント + - botの場合も含む +- `system`: システム通知 + - モデレーター等からの警告通知など + +`account`: + +```jsonc +{ + "type": "account", + "account": { + // アカウントID + "id": "209384", + // アカウント名 + "name": "@johndoe@example.com", + // アカウントニックネーム + "nickname": "John Doe🌤", + // アバター画像のURL + "avatar": "https://cdn.example.com/johndoe/avater" + } +} +``` + +`system`: + +```jsonc +{ + "type": "system", + "system": { + } +} +``` + +## `GET /notifications` + +届いているすべての通知を取得します。すでに既読がついている通知は表示されません。 + +### 入力 + +なし + +### 出力 + +- body: `application/json` + +```jsonc +{ + // インスタンス全体へのお知らせ + "announcements": [ + { + "id": "308205359", + "title": "Service maintenance", + "description": "scheduled: 2024 Sep. 10 00:00 ~ 01:00(UTC)\nduring this period, all services will be unavailable.", + // お知らせの種類 + "type": "info", + "createdAt": "2024-08-01T00:00:00.000Z", + // optional + "updatedAt": "2024-08-01T10:00:00.000Z", + // 既読か + "unread": false + } + ], + // 自分宛ての通知 + "notifications": [ + { + "id": "20923084093774", + "type": "followed", + "actor": { + "type": "account", + "account": { + "id": "209384", + "name": "@johndoe@example.com", + "nickname": "John Doe🌤", + "avatar": "https://cdn.example.com/johndoe/avater" + } + }, + "createdAt": "2024-08-01T00:00:00.000Z" + } + ] +} +``` + + + +## `POST /notifications/{id}/read` + +通知を既読にします + +### 入力 + +- パスパラメータ + - `id`: string + - 既読にする通知ID + +- body: `application/json` + +```jsonc +{} +``` + +### 出力 + +**`204 No Content`** 通知を既読にしました。 From 0156fcb4f904fa32530de29523d7cf2519645b49 Mon Sep 17 00:00:00 2001 From: Tatsuto YAMAMOTO Date: Thu, 29 Aug 2024 22:00:13 +0900 Subject: [PATCH 2/6] chore: format --- src/endpoint/notification.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/endpoint/notification.md b/src/endpoint/notification.md index 96f5c28..cb0f9b2 100644 --- a/src/endpoint/notification.md +++ b/src/endpoint/notification.md @@ -245,8 +245,6 @@ } ``` - - ## `POST /notifications/{id}/read` 通知を既読にします From 362252b5bc20a29c96b12d9f5352e528fe6e66c8 Mon Sep 17 00:00:00 2001 From: Tatsuto YAMAMOTO Date: Thu, 29 Aug 2024 23:27:53 +0900 Subject: [PATCH 3/6] fix: headings --- src/endpoint/notification.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/endpoint/notification.md b/src/endpoint/notification.md index cb0f9b2..2ed51af 100644 --- a/src/endpoint/notification.md +++ b/src/endpoint/notification.md @@ -1,17 +1,17 @@ # 通知API -#### お知らせ（Announce)の種類 +## お知らせ（Announce)の種類 | 種類コード | 説明 | | :--------: | :------------------: | | `info` | 一般的なお知らせ | | `warn` | ユーザー全体への警告 | -#### 通知の種類 / `actor`の種類 +## 通知の種類 / `actor`の種類 通知の種類 -##### `followed` - フォローされた +## `followed` - フォローされた 取り得る`actor`の種類: @@ -34,7 +34,7 @@ } ``` -##### `followRequested` - フォローをリクエストされた +## `followRequested` - フォローをリクエストされた 取り得る`actor`の種類: @@ -57,7 +57,7 @@ } ``` -##### `followAccepted` - (自分が行った)フォローが承認された +## `followAccepted` - (自分が行った)フォローが承認された 取り得る`actor`の種類: @@ -80,7 +80,7 @@ } ``` -##### `mentioned` - メンションされた +## `mentioned` - メンションされた 取り得る`actor`の種類: @@ -105,7 +105,7 @@ } ``` -##### `renoted` - リノートされた +## `renoted` - リノートされた 取り得る`actor`の種類: @@ -132,7 +132,7 @@ } ``` -##### `reacted` - リアクションされた +## `reacted` - リアクションされた 取り得る`actor`の種類: @@ -159,7 +159,7 @@ } ``` -##### `actor`について +## `actor`について 通知を発生させた主体の種類 From 47e4401f42b1903de4a7888c3cca72720e9459f3 Mon Sep 17 00:00:00 2001 From: Tatsuto YAMAMOTO Date: Fri, 30 Aug 2024 09:23:05 +0900 Subject: [PATCH 4/6] feat: add query params to GET /notifications --- src/endpoint/notification.md | 52 +++++++++++++++++++++++------------- 1 file changed, 34 insertions(+), 18 deletions(-) diff --git a/src/endpoint/notification.md b/src/endpoint/notification.md index 2ed51af..74f59e1 100644 --- a/src/endpoint/notification.md +++ b/src/endpoint/notification.md @@ -7,11 +7,18 @@ | `info` | 一般的なお知らせ | | `warn` | ユーザー全体への警告 | -## 通知の種類 / `actor`の種類 +## 通知の種類 -通知の種類 +| 種類コード | 通知が発生する条件 | +| :--: | :----: | +| `followed` | フォローされたとき | +| `followRequested` | フォローをリクエストされたとき | +| `followAccepted` | 自分が行ったフォローリクエストが承認されたとき | +| `mentioned` | メンションされたとき | +| `renoted` | リノートされたとき | +| `reacted` | リアクションされたとき | -## `followed` - フォローされた +### `followed` - フォローされた 取り得る`actor`の種類: @@ -34,7 +41,7 @@ } ``` -## `followRequested` - フォローをリクエストされた +### `followRequested` - フォローをリクエストされた 取り得る`actor`の種類: @@ -57,7 +64,7 @@ } ``` -## `followAccepted` - (自分が行った)フォローが承認された +### `followAccepted` - (自分が行った)フォローリクエストが承認されたとき 取り得る`actor`の種類: @@ -80,7 +87,7 @@ } ``` -## `mentioned` - メンションされた +### `mentioned` - メンションされた 取り得る`actor`の種類: @@ -105,7 +112,7 @@ } ``` -## `renoted` - リノートされた +### `renoted` - リノートされた 取り得る`actor`の種類: @@ -132,7 +139,7 @@ } ``` -## `reacted` - リアクションされた +### `reacted` - リアクションされた 取り得る`actor`の種類: @@ -159,7 +166,7 @@ } ``` -## `actor`について +#### `actor`について 通知を発生させた主体の種類 @@ -192,19 +199,28 @@ { "type": "system", "system": { + // ToDo } } ``` -## `GET /notifications` +## APIエンドポイント一覧 -届いているすべての通知を取得します。すでに既読がついている通知は表示されません。 +### `GET /notifications` -### 入力 +届いているすべての通知を取得します。 -なし +#### 入力 -### 出力 +パスパラメータ: +- `limit`: number, 返す通知の最大数 + - デフォルト: 30 / 最大: 50 +- `after`: string(date), この日以降の通知を返します + - デフォルト: "1970-01-01" +- `include_read`: boolean, trueの時は既読の通知も返します + - デフォルト: false + +#### 出力 - body: `application/json` @@ -236,7 +252,7 @@ "id": "209384", "name": "@johndoe@example.com", "nickname": "John Doe🌤", - "avatar": "https://cdn.example.com/johndoe/avater" + "avatar": "https://cdn.example.com/johndoe/avatar" } }, "createdAt": "2024-08-01T00:00:00.000Z" @@ -245,11 +261,11 @@ } ``` -## `POST /notifications/{id}/read` +### `POST /notifications/{id}/read` 通知を既読にします -### 入力 +#### 入力 - パスパラメータ - `id`: string @@ -261,6 +277,6 @@ {} ``` -### 出力 +#### 出力 **`204 No Content`** 通知を既読にしました。 From 555340e4f249888fa7dc6fb837949fbb257c080b Mon Sep 17 00:00:00 2001 From: Tatsuto YAMAMOTO Date: Fri, 30 Aug 2024 09:24:00 +0900 Subject: [PATCH 5/6] fix: format --- src/endpoint/notification.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/endpoint/notification.md b/src/endpoint/notification.md index 74f59e1..74bcb7f 100644 --- a/src/endpoint/notification.md +++ b/src/endpoint/notification.md @@ -9,14 +9,14 @@ ## 通知の種類 -| 種類コード | 通知が発生する条件 | -| :--: | :----: | -| `followed` | フォローされたとき | -| `followRequested` | フォローをリクエストされたとき | +| 種類コード | 通知が発生する条件 | +| :---------------: | :--------------------------------------------: | +| `followed` | フォローされたとき | +| `followRequested` | フォローをリクエストされたとき | | `followAccepted` | 自分が行ったフォローリクエストが承認されたとき | -| `mentioned` | メンションされたとき | -| `renoted` | リノートされたとき | -| `reacted` | リアクションされたとき | +| `mentioned` | メンションされたとき | +| `renoted` | リノートされたとき | +| `reacted` | リアクションされたとき | ### `followed` - フォローされた @@ -213,6 +213,7 @@ #### 入力 パスパラメータ: + - `limit`: number, 返す通知の最大数 - デフォルト: 30 / 最大: 50 - `after`: string(date), この日以降の通知を返します From 6279a4f6e1576912d71abbbcc77c95803792853a Mon Sep 17 00:00:00 2001 From: Tatsuto YAMAMOTO Date: Fri, 30 Aug 2024 18:34:18 +0900 Subject: [PATCH 6/6] chore: fix typo --- src/endpoint/notification.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/endpoint/notification.md b/src/endpoint/notification.md index 74bcb7f..eed8e0b 100644 --- a/src/endpoint/notification.md +++ b/src/endpoint/notification.md @@ -34,7 +34,7 @@ "id": "209384", "name": "@johndoe@example.com", "nickname": "John Doe🌤", - "avatar": "https://cdn.example.com/johndoe/avater" + "avatar": "https://cdn.example.com/johndoe/avatar" } }, "createdAt": "2024-08-01T00:00:00.000Z" @@ -57,7 +57,7 @@ "id": "209384", "name": "@johndoe@example.com", "nickname": "John Doe🌤", - "avatar": "https://cdn.example.com/johndoe/avater" + "avatar": "https://cdn.example.com/johndoe/avatar" } }, "createdAt": "2024-08-01T00:00:00.000Z" @@ -80,7 +80,7 @@ "id": "209384", "name": "@johndoe@example.com", "nickname": "John Doe🌤", - "avatar": "https://cdn.example.com/johndoe/avater" + "avatar": "https://cdn.example.com/johndoe/avatar" } }, "createdAt": "2024-08-01T00:00:00.000Z" @@ -105,7 +105,7 @@ "id": "209384", "name": "@johndoe@example.com", "nickname": "John Doe🌤", - "avatar": "https://cdn.example.com/johndoe/avater" + "avatar": "https://cdn.example.com/johndoe/avatar" } }, "createdAt": "2024-08-01T00:00:00.000Z" @@ -132,7 +132,7 @@ "id": "209384", "name": "@johndoe@example.com", "nickname": "John Doe🌤", - "avatar": "https://cdn.example.com/johndoe/avater" + "avatar": "https://cdn.example.com/johndoe/avatar" } }, "createdAt": "2024-08-01T00:00:00.000Z" @@ -159,7 +159,7 @@ "id": "209384", "name": "@johndoe@example.com", "nickname": "John Doe🌤", - "avatar": "https://cdn.example.com/johndoe/avater" + "avatar": "https://cdn.example.com/johndoe/avatar" } }, "createdAt": "2024-08-01T00:00:00.000Z" @@ -188,7 +188,7 @@ // アカウントニックネーム "nickname": "John Doe🌤", // アバター画像のURL - "avatar": "https://cdn.example.com/johndoe/avater" + "avatar": "https://cdn.example.com/johndoe/avatar" } } ```