...

• People API
  グループを指定してそのメンバーに関する情報を取得するためのAPI
• Groups API
  SPコネクタに接続しているグループに関する情報を取得するためのAPI
• New Group API
  新たなグループから接続があった場合にGakuNin mAPから呼び出されるSPのAPI

いずれも、認証は学認におけるSPメタデータに記載されている証明書を用いたTLSクライアント証明書認証により行います。証明書の extended Key Usage (eKU) に clientAuth が記載されていなければなりません。
また、mAPが提示する証明書も学認におけるSPメタデータに記載されているものとなりますので、SP側で適切に検証してください。

...

※ <グループentityID> は、isMemberOfで取得することができるURL形式の値（のJavaScriptでの表現）
　例: "https:\/\/map.gakunin.nii.ac.jp\/gr\/GakuNinTF"
※ このAPIで取得できるグループはSPコネクタに直接接続しているもののみです。上位グループ経由で接続している下位グループのグループ情報は含まれません。
※ <グループのメンバー数> には、管理者のみの人（管理者であるがメンバーでない人）は含まれません。また、属性送信に同意しているかどうかに関わらずカウントされますので、people APIを通して取得した数より大きい可能性があります。
※ 特に、文字列中にUnicodeのコード表記（例:\u3042）の形式の文字を含む可能性があります。

New Group API

リクエストURL

• URLのフォーマットは特に定めません。SPコネクタの設定項目の一つである「New Group API」欄にSP側のAPIのURLを登録してください。

• URLに以下の変数を含めると、API呼び出し時に当該部分がGakuNin mAPが持つ情報で置換されます。

  変数名	置換される値
  $groupID	グループID（グループentityIDの短縮形）
  $adminEmail	接続を行ったグループ管理者のメールアドレス（つまり当該グループに管理者が複数人いても1つのみ渡されます）

• 例えばmeatmailでは以下のように登録しており、

  書式設定済み
  https://meatmail.nii.ac.jp/meatmail-api/newlist/$groupID/$adminEmail

  実際の呼び出し例は以下のようになります。

  書式設定済み
  https://meatmail.nii.ac.jp/meatmail-api/newlist/TestGroup/user%40example.jp

  注意
  グループ管理者の操作によって、同じリクエストが複数あることがあります。そのため、問題がない場合はOKを返すようにしてください。 例えば、メーリングリストの作成リクエストの1回目は実際にメーリングリストを作成し、2回目は既に作成されているのでそのままOKを返します。

レスポンス

上記リクエストのレスポンスを以下に示します。SP側では下記のようなJSON形式で、GakuNin mAPにレスポンスを返す必要があります。

成功時

{
 "result" :  "OK",
 "message" : "メッセージ"
}

失敗時

{
 "result" :  "NG",
 "message" : "メッセージ"
}

result

HTTPステータス

※ HTTPステータスが200以外の場合、および上記resultがNGの場合は、接続したグループ管理者に対して「meatmailへのAPI呼び出しが失敗しました」と画面にメッセージが表示されます。

サーバ認証およびクライアント認証

GakuNin mAPからのリクエストではTLSクライアント証明書認証を使います。
学認フェデレーションのメタデータにあるGakuNin mAP（entityID:https://map.gakunin.nii.ac.jp/idp/shibboleth）の証明書を使いSPにリクエストします。
SP側ではリクエストを受け取った際に、GakuNin mAPの証明書であることを確認してください。

また、mAP側はTLSサーバ証明書認証によりリクエスト先の正当性確認を行ないます。登録したURLのスキームがHTTPSであること、および当該URLのサーバ証明書がSPメタデータに記載されたものと一致することをご確認ください。

エラーレスポンス（共通）

...