FEP-9fde: サポートされている操作を公開するためのサーバー向けメカニズム

以下は本提案において明示的に回答していない疑問点です。私なりの見解を述べますが、ご意見をいただければ幸いです。

サーバー側でAPIパスのプレフィックスを指定することは可能か？

すべての操作のURLパス構成要素を自由に変更できるべきではないと考えますが、特定の操作または全ての操作に対してパスプレフィックスを指定できるようにすることは、場合によっては有用かもしれません。

例えば、MastodonとFriendicaのAPIをサポートするサーバーが、それぞれmastodonおよびfriendicaで始まるパスでこれらを提供したい場合などです。

この方式を採用する場合、マップ値としてprefixキーとversionsキーを持つオブジェクトを使用する必要があります。

"operations": {
    "org.joinmastodon.api.conversations.id.unread": {
        "prefix": "/mastodon",
        "versions": ["1.0.0"]
    },
    "ca.friendi.api.conversations.id.unread": {
        "prefix": "/friendica",
        "versions": ["1.0.0"]
    }
}

prefixが省略された場合、デフォルトは/となります。

このフォーマットを採用すること自体は、将来的に後方互換性を保ちつつ変更を加えるための良い方法と考えられます。特にversionsキーのみを使用する場合でも同様です。

FQDN所有者のリブランディングやサービス終了が発生した場合、操作識別子はどうなるか？

FQDNを所有するエンティティが名称を変更したりサービスを停止した場合、すでに定義されている操作識別子はどう扱われるべきでしょうか？

私の考えでは、単にリブランディングしたからといって全ての操作識別子を全面的に改名するのは過剰な手間です。彼らは新しい名前で今後の操作を定義し直すという選択肢もあります。

操作識別子が実際のドメイン/URLではないため、それらが実際に解決される必要はありません。したがって、あるプロジェクトが操作識別子を定義した後にサービスを停止した場合でも、API仕様に関する文書が残っていれば何も失われることはありません。

逆FQDNにサフィックスを追加する方式は、操作キーとして最適な形式か？

私はこれが最適だと考えています。

Uniform Resource Name（URN）やInternationalized Resource Identifiers（IRI）の使用も検討しました。これらには利点もあります。例えば、操作識別子がAPI仕様文書（おそらくOpenAPI定義）に解決されるURNまたはIRIとして機能することが考えられます。

しかし、これによりクライアントがサーバーから返された操作リストと自身のサポートしている操作を比較する際に、大文字小文字の扱いという難しい問題が生じます。

もし操作キーがURNまたはIRIであれば、その性質上部分的には大文字小文字が区別されます。これにより、サーバー開発者が誤ったケースで識別子を報告したり、クライアント開発者が正しいケースで検索を行わなかったりする可能性があり、相互運用性に支障をきたす恐れがあります。

「クライアントは比較前に操作識別子をすべて小文字に変換すべき」という提案では、この問題を解決できません。テキストの正しい小文字化規則は明確に定義されておらず、実装によって異なる場合があるため、やはり相互運用性に問題が生じます。

逆FQDNに追加ラベルを付け、IDN形式でエンコードする方式であれば、これらの問題を回避できます。

API呼び出しと操作の間に1対1の対応関係を設けるべきか？

サポートされるすべてのAPI呼び出しに対して必ず対応する操作を定義すべきか、あるいは複数のAPI呼び出しを単一の操作として扱うことが許容されるべきでしょうか？

私は1対1のマッピングが最も合理的だと考えます。これにより、サーバー開発者は新機能を段階的に展開することが可能になります。

例えば、執筆時点でFriendicaはまだ投票機能を完全には実装していません。投票付き投稿を表示したりAPIで取得したりすることは可能ですが、投票用ポストを作成する操作や投票を行う操作は未実装です。

APIと操作の間に1対1の対応関係があれば、Friendicaサーバーは「私は投票を含む可能性のある投稿を返すことができます。ただし、投票を作成したり投票したりするAPIコールには対応していません」と表明できます。

もし「投票機能」を単一の操作として扱えば、Friendicaは「私は投票をサポートしていない」と表明せざるを得なくなり、クライアントが不必要にFriendicaポストに添付された投票を表示しない事態を招く可能性があります。

1対1以外のマッピング方式を採用すると、異なるサーバー開発チームがそれぞれ異なる方法でAPI呼び出しを単一の操作にまとめる可能性が生じ、結果としてクライアント開発者にとって複雑さが増すことになります。

リクエスト時にクライアントは操作識別子を指定すべきか？

単一のエンドポイントで複数バージョンのAPIをサポートしている場合、クライアントが使用しているAPIの正確なバージョンを確実に判定することは困難です。多くの場合、サーバーソフトウェアは「スニッフィング」（リクエスト内容を解析し、特定のプロパティの有無からクライアントの意図を推測する手法）に頼らざるを得ません。

これにより、リクエスト処理コードの記述や、クライアントに返すべきエラー情報の決定がより複雑になります。

この問題の解決は本提案の範囲外と考えます。ただし、本提案が採用された場合、サーバー開発者にはAPI変更時に必須の特定プロパティとして操作IDを含めるよう推奨します。こうすることで、徐々にこの問題が解決されていくでしょう。

これはnodeinfoに新しいトップレベルキーを追加する必要のある仕様か？

いいえ、metadataセクションに含めることも可能です。以下のように公開できます：

{
  "version": "2.2",
  ...
  "metadata": {
    "operations": {
      // 操作データはここに記述
    }
  }
}

参考文献

著作権

CC0 1.0 Universal（パブリックドメイン献呈）

法律で許される範囲において、本Fediverse Enhancement Proposalの著者らはこの著作物に関するすべての著作権および関連権利を放棄しています。