投稿参照API - kmycode/mastodon GitHub Wiki

対応可否の判定方法

下記のエンドポイントで取得できるJSONについて

/api/v1/instance
/api/v2/instance

下記の配列に値があるかで判定してください

{
  "fedibird_capabilities": [
    "status_reference"
  ]
}

Fedibird互換情報

当サーバーの投稿参照機能はFedibirdと互換性があります。

既存のオブジェクトに追加されたプロパティ

statusオブジェクトに以下のプロパティが追加されています。

{
  "status_reference_ids": "（数値配列）この投稿が参照した投稿のID一覧",
  "status_references_count": "（数値）この投稿が参照した投稿の数",
  "status_referred_by_count": "（数値）この投稿を参照した投稿の数"
}

通知に追加されたイベント

status_reference通知が追加されています。この通知は自分の投稿が別のアカウントにより参照された時に発生します。通知オブジェクトの内容はmentionと同一で、target_statusプロパティには参照したほうの投稿が格納されます。

既存のAPIに追加されたプロパティ

新規投稿

新規statusを作成するAPI（投稿するAPI）に、下記のプロパティが追加されています。

POST /api/v1/statuses

{
  "status_reference_ids": "（数値配列）投稿が参照する投稿IDの一覧"
}

本文内の参照に、このプロパティで別途指定された投稿が追加されます。

投稿編集

既存statusを編集するAPIに、下記のプロパティが追加されています。

PUT /api/v1/statuses/:statusId

{
  "status_reference_ids": "（数値配列）投稿が参照する投稿IDの一覧"
}

本文内の参照に、このプロパティで別途指定された投稿が追加されます。これは差分ではなく、既存のデータを置き換えるものです。そのため編集時にも、完全な参照の一覧を指定する必要があります。

追加されたAPI

投稿が参照した投稿一覧

投稿の返信・返信先（スレッドの先祖子孫）を取得するAPIの戻り値に、以下のプロパティが追加されています。

GET /api/v1/statuses/:statusId/context

パラメータ名	例	説明
`with_reference`	`1`	指定された場合、`ancestors`と`references`を分離します (`9.0`以降)

戻り値

このAPIはVer 9.0で破壊的変更が加えられています。kmyblue独自の挙動をあらため、Fedibirdと互換の動きになるようにしたものです。ただしVer 9.0より前のバージョンでwith_referenceパラメータを指定してもエラーにはならないため、クライアントアプリ側では「with_referenceパラメータは常に指定する。戻り値にreferenceプロパティが含まれていればそれを見て処理する」というように実装したほうが楽ではないかと思います。

以下の戻り値が返ってくるのは、以下のいずれかの条件を満たした場合です

Ver 9.0 より前（5.x LTS含む）
Ver 9.0以降でwith_referenceパラメータを指定した場合

{
  "ancestors": "（Status配列）この投稿が返信元として設定した投稿オブジェクト",
  "references": "（Status配列）この投稿が参照した投稿オブジェクトの一覧"
}

以下の戻り値が返ってくるのは、以下の条件を満たした場合です

Ver 9.0以降でwith_referenceパラメータを指定しなかった場合

{
  "ancestors": "（Status配列）この投稿の返信元、ならびに参照した投稿オブジェクトの一覧",
  "references": "（Status配列）常に空の配列"
}

投稿を参照した投稿一覧

以下のAPIが追加されています。これは、この投稿を参照した投稿一覧を取得するものであり、戻り値には投稿のみが格納された単純な配列が返されます。

GET /api/v1/statuses/:statusId/references

投稿本文での参照指定フォーマット

上記APIで指定する他にも、投稿本文に投稿のURLを直接記述することで、参照とすることが可能です。これはkmyblue独自の仕様であり、他のサーバーからの投稿に対しても適用されます。
status_reference_idsに参照先投稿IDを別途指定する必要はありません。重複で指定されていた場合はエラーとならず、参照一覧は重複する要素が除外されます。

投稿本文内からは、以下の正規表現を使用して参照を抽出します。

/(RT|QT|BT|RN|RE)((:|;)?\s+|:|;)(#{URI::DEFAULT_PARSER.make_regexp(%w(http https))})/

なお上記のうちQT、REは、最初のリンクが引用として扱われます。（kmyblueの内部処理において、引用は参照の特別な形態となっています）

例えば以下のフォーマットは有効です。

BT https://kmy.blue/@account/statuses/00000000000000    --- 参照
RN: https://kmy.blue/@account/statuses/00000000000000   --- 参照
RE:https://kmy.blue/@account/statuses/00000000000000    --- 引用
QT:  https://kmy.blue/@account/statuses/00000000000000  --- 引用
RT    https://kmy.blue/@account/statuses/00000000000000 --- 参照