タイムライン

main ブランチの最新 API リファレンスは api.pulsate.dev/reference で閲覧可能.

APIのバージョニング

APIの規定パス(Base Path)は /api/v0 である.

APIのバージョンは以下の通り.

バージョン	ステータス
v0	策定途中

資格情報が必要なエンドポイントの実行方法

Pulsate v0 APIでは殆どのエンドポイントで資格情報が必要である.

資格情報が必要なエンドポイントへアクセスするためには, 以下の方法でエンドポイントにアクセスする必要がある.

エンドポイントへアクセスするときのAuthorization HTTPヘッダーに

Bearer <token>

の形式で認証トークンをつけて送信する必要がある.

例:

Bearer

“文字数”の扱い

特に明記しない限り、文字数は 以下のコードを実行して計算できる文字数 とする.

const count = (s: string) => {
  const segmenter = new Intl.Segmenter({ granularity: "word" });
  return [...segmenter.segment(s)].length;
};

このAPIを実装する実行環境のリストはMDNを参照せよ.

Intl.Segmenter - JavaScript | MDN

“時刻/時間”の扱い

特に明記しない限り、システム上の時刻の扱いは以下の通りである.

日時は例外なくタイムゾーンをUTCとして扱う
時刻のフォーマットは ISO 8601 とする.
- "yyyy-MM-DDTHH:mm:ss.SSSZ"形式
- タイムゾーン指定されていた場合は指定したタイムゾーンの日時をUTCに変換する.
  - 例:
    - 2023-11-21T09:00:00.000+09:00 : 日本時間(JST, UTC+9) 2023年11月21日09:00:00.000 → 2023-11-21T00:00:00.000Z : 世界協定時(UTC) 2023年11月21日00:00:00.000
- 以上の形式に合致しない形で日時の表現がされた場合はエラー終了するものとする.

絵文字の扱い

絵文字とは, Unicodeによって定義される絵文字とカスタム絵文字のことである.

その他の記号や環境依存文字は絵文字ではないとする.

Unicode絵文字

Unicode絵文字とは,Unicodeによって定義される絵文字である.

APIとやり取りするテキストデータでは特殊な記法を用いずUnicodeで表現する.

例:

{
  "content": "🎉"
}

カスタム絵文字

カスタム絵文字を文字列内に埋め込むための形式は以下の通りである.

以下の形式に沿わない場合は単なる文字列であると解釈する.

全体を<> で囲む
- カスタム絵文字のエイリアスは::で囲む
- カスタム絵文字に関する詳細な定義はここでは行わない. (ToDo)
エイリアスのあとに(絵文字があるインスタンスではなく,APIを提供するインスタンスでの)カスタム絵文字のIDを表記する.

例:

<:alias:2949583895994> <:ii_hanashi:284745363>

特殊なテキスト埋め込みオブジェクト

投稿本文, CW注釈, アカウントbio のテキスト内にカスタム絵文字やメンションなど, Unicodeで規定された文字以外のデータを表現するときの記法

カスタム絵文字はカスタム絵文字を参照せよ.

メンション

表記法は以下の通り

メンションは<>で囲む
囲んだ中にアカウント名を入れる
- RFC 7565で規定される形式のスキームであるacct:を取り除き, @に置き換えたもの
- 例: アカウント名が @[email protected]である場合

<@[email protected]>

宛先のホスト名(FQDN)は 省略不可

<@[email protected]> <@[email protected]> <@[email protected]>

基本エラーオブジェクト

APIにおいて何らかのエラーが発生した際には以下のようなエラーオブジェクトを返却する.

{
  "error": "TEST_ERROR_CODE"
}

errorの中にはエラーコード が入る. エラーコードはエラーを返却するAPIのエンドポイントでどのようなコードを返すか指定するものとする.

エラーオブジェクトはエラーコードのみをメンバーとして含むオブジェクトである.

エラーコード以外の情報をエラーオブジェクトとして返却することは許容されない.

NSFWフラグ

言葉の意味:

NSFWとは、英語圏で用いられるインターネットスラングで、「職場では見ない方がいい」（職場での閲覧は危険）という意味の略語である。日本語の「閲覧注意」におおむね相当する。

NSFWは画像がメインの掲示板や、掲示板中の画像へのリンクなどに付けて用いられやすい。たいていは卑猥（エロ画像）・残酷（グロ画像）といった要素の強い、不用意な閲覧ははばかられる類のコンテンツが掲載されている。

NSFWフラグとは,画像/音声/動画の内容がNSFWであることを示すためのフラグである.
大抵の場合画像/音声/動画にぼかし(ブラー)がかけられたり,閲覧注意の文言が(システムのUI上で)表示される.

ContentsWarning/CWフラグ

CWフラグとは,投稿本文に何らかのコンテンツ警告があることを示すフラグである.
大抵の場合,投稿の注釈(投稿本文より短い,本文の内容を端的に表した文)のみが表示され,本文は[続きを読む]といったボタンを押さないと見ることができない

リファレンスへの追加状況 (See: pulsate-dev/specification#3 )
- アカウント
  - アカウント情報(プロフィール)を管理する
  - アカウント情報の取得
  - アカウントの削除
  - アカウントの検索
  - アカウントのサイレンス
  - アカウトのサイレンス解除
  - アカウントの凍結
  - アカウトの解凍
  - ログイン
  - アカウント登録
- フォロー
  - アカウントをフォロー
  - アカウントをフォロー解除
- ノート
  - ノートの作成
  - (自分の)ノートの削除
  - リノートの作成
  - リノートの解除(削除)
  - ノートへのリアクションの作成
  - ノートへのリアクションの解除
  - ノートのブックマーク
  - ノートの検索
  - ノートの取得
- リスト
  - リストの作成
  - リストの削除
  - リストへのアカウントの追加
  - リストへのアカウントの除外/削除
  - リストのノート取得
- ドライブ
  - ファイルのアップロード
  - ファイルの取得
  - ノートへの紐付け
  - NSFWフラグの設定

Pulsate Specification