APIについて

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

APIのバージョニング

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

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

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

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

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

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

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

Bearer <token>

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

例:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

資格情報が必要ないエンドポイントについて Pulsate v0 APIでは、資格情報が必要なエンドポイントであっても、資格情報がない場合にアクセス可能なエンドポイントが存在する。
例えば、あるアカウントのタイムラインを取得するエンドポイントの場合:

有効な資格情報がある場合
- フォローしている場合は FOLLOWER 公開範囲の投稿も返す
- フォローしていない場合は資格情報がない場合と変わらない
資格情報が無効な場合
- 認証トークンが期限切れや改ざんされている場合
- 認証エラーを返す
資格情報がない場合
- Authorizationヘッダーが空の場合
- PUBLIC/HOME 公開範囲の投稿を返す

“文字数”の扱い

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

const count = (s: string) => {
  const segmenter = new Intl.Segmenter("ja-JP", { granularity: "grapheme" });
  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フラグとは,投稿本文に何らかのコンテンツ警告があることを示すフラグである.
大抵の場合,投稿の注釈(投稿本文より短い,本文の内容を端的に表した文)のみが表示され,本文は[続きを読む]といったボタンを押さないと見ることができない

Pulsate Specification