Link v2 API クライアント
PocketSign Link v2 の IdP API および Registry API は、いずれも Connect プロトコル に対応しています。 クライアントライブラリは Buf Schema Registry から入手できます。
クライアントライブラリが提供されない言語でも、Connect プロトコルは gRPC-Web や通常の HTTP API としても利用できます。
対象サービス
PocketSign Link v2 は、認証認可を担う IdP と、リソースを管理する Registry の 2 系統のサーバーで構成されます。 それぞれが ConnectRPC で次の 4 つのサービスを提供しています。
| サービス | 提供サーバー | 用途 |
|---|---|---|
pocketsign.link.v2.IdPUserService | IdP | OIDC アクセストークンに紐づくユーザー本人の操作 |
pocketsign.link.v2.IdPClientService | IdP | サービスアクセストークンによる指定ユーザーの操作 |
pocketsign.link.v2.RegistryUserService | Registry | OIDC アクセストークンに紐づくユーザー本人のリソース読み書き |
pocketsign.link.v2.RegistryClientService | Registry | サービスアクセストークンによる指定ユーザーのリソース読み書き |
UserService 系はユーザーアクセストークン（OIDC で取得）を、ClientService 系はサービスアクセストークンを Authorization ヘッダーに設定します。
各サービスのオリジンは環境ごとに異なります。詳細は 環境 を参照してください。
ライブラリを使用せずに呼び出す
クライアントライブラリが提供されない言語からは、Connect プロトコルの互換動作として gRPC-Web や通常の HTTP API としても呼び出せます。
URL の組み立て方
すべての RPC は、サービスの提供サーバーのオリジン配下に次の形式のパスで公開されています。
{オリジン}/{パッケージ}.{サービス名}/{RPC 名}
環境ごとのオリジンは 環境 を参照してください。
HTTP
通常の HTTP ベース API として利用できます。
curl -v 'https://registry.mock.klon.you/pocketsign.link.v2.RegistryUserService/ReadResourceValues' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
--data '{"idOrAliases":["klon/merged_full_name"]}'
呼び出し対象サービス・メソッドに応じて、URL の {オリジン} および {サービス名}/{RPC 名} 部分を読み替えてください。
HTTP による呼び出しは、内部的には Connect プロトコルによる呼び出しです。 Connect プロトコルの詳しい仕様は Connect Protocol Reference を参照してください。
Protobuf による API 定義 において、idempotency_level = NO_SIDE_EFFECTS が設定されている RPC については、GET メソッドでの呼び出しもサポートしています。
gRPC-Web
buf curl -v 'https://registry.mock.klon.you/pocketsign.link.v2.RegistryUserService/ReadResourceValues' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-d '{"idOrAliases":["klon/merged_full_name"]}' \
--schema 'buf.build/pocketsign/apis' \
--protocol grpcweb
DPoP バインドされたアクセストークンを使う
UserService 系を DPoP バインドされたユーザーアクセストークンで呼び出す場合は、通常の Authorization: Bearer ではなく Authorization: DPoP <ACCESS_TOKEN> と DPoP: <PROOF_JWT> の 2 ヘッダーをリクエストごとに付与する必要があります。
DPoP の仕様や proof JWT の作り方については DPoP を参照してください。