...
- People API
グループを指定してそのメンバーに関する情報を取得するためのAPI - Groups API
SPコネクタに接続しているグループに関する情報を取得するためのAPI - New Group API
新たなグループから接続があった場合にGakuNin mAPから呼び出されるSPのAPImAP（クラウドゲートウェイ）から呼び出されるSPのAPI
いずれも、認証は学認におけるSPメタデータに記載されている証明書を用いたTLSクライアント証明書認証により行います。証明書の extended Key Usage (eKU) に clientAuth が記載されていなければなりません。
また、mAPが提示する証明書も学認におけるSPメタデータに記載されているものとなりますので、SP側で適切に検証してください。
...
言語 はオプション項目であり、レスポンスで返す言語を指定します。
指定できるTYPEは、en と ja で、下記の優先順位でレスポンスを返します。
リクエストURLの言語指定 ＞ 英語入力 ＞ 日本語入力
なお、英語、日本語ともGakuNin mAPに登録がなければ、当該属性自体が存在しない状態で返します。mAP（クラウドゲートウェイ）に登録がなければ、当該属性自体が存在しない状態で返します。
下記に例を示します。
GakuNin mAPに、氏名「日／英」、自己紹介「英」、所属「日／英とも空欄」で登録されていた場合、mAP（クラウドゲートウェイ）に、氏名「日／英」、自己紹介「英」、所属「日／英とも空欄」で登録されていた場合、
リクエストの言語指定が「ja」であった場合は、氏名「日」、自己紹介「英」、所属「無し」を、
リクエストの言語指定が「en」であった場合は、氏名「英」、自己紹介「英」、所属「無し」を、
リクエストの言語指定がない場合は、氏名「英」、自己紹介「英」、所属「無し」を返します。
...
言語 はオプション項目で、レスポンスで返す言語を指定します。
指定できるTYPEは、enとjaであり、下記の優先順位でレスポンスを返します。
リクエストURLの言語指定 ＞ 英語入力 ＞ 日本語入力
なお、英語、日本語ともGakuNin mAPに登録がなければ、当該属性自体が存在しない状態で返します。mAP（クラウドゲートウェイ）に登録がなければ、当該属性自体が存在しない状態で返します。
下記に例を示します。
GakuNin mAPに、グループ名「日／英」、紹介文「日」で登録されていた場合、mAP（クラウドゲートウェイ）に、グループ名「日／英」、紹介文「日」で登録されていた場合、
リクエストの言語指定が「ja」であった場合は、グループ名「日」、紹介文「日」を、
リクエストの言語指定が「en」であった場合は、グループ名「英」、紹介文「日」を、
リクエストの言語指定がない場合は、グループ名「英」、紹介文「日」を返します。
...
- URLのフォーマットは特に定めません。SPコネクタの設定項目の一つである「New Group API」欄にSP側のAPIのURLを登録してください。
URLに以下の変数を含めると、API呼び出し時に当該部分がGakuNin mAPが持つ情報で置換されます。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にレスポンスを返す必要があります。mAP（クラウドゲートウェイ）にレスポンスを返す必要があります。
成功時
| 書式設定済み |
|---|
{
"result" : "OK",
"message" : "メッセージ"
} |
...
| 項目 | 必須 | 説明 |
|---|---|---|
result | ○ | 成功時はOK、失敗時はNGを設定します。 |
| message | ○ | 成功時、失敗時ともメッセージを入れてください。現状これはGakuNin mAPのログに記録されるのみです。mAP（クラウドゲートウェイ）のログに記録されるのみです。 |
HTTPステータス
| HTTPステータス | 説明 |
|---|---|
| 200 | GakuNin mAPからリクエストを受け付けた場合、ステータスを200で返してくださいmAP（クラウドゲートウェイ）からリクエストを受け付けた場合、ステータスを200で返してください |
※ HTTPステータスが200以外の場合、および上記resultがNGの場合は、接続したグループ管理者に対して「meatmailへのAPI呼び出しが失敗しました」と画面にメッセージが表示されます。
サーバ認証およびクライアント認証
GakuNin mAPからのリクエストではTLSクライアント証明書認証を使います。mAP（クラウドゲートウェイ）からのリクエストではTLSクライアント証明書認証を使います。
学認フェデレーションのメタデータにあるGakuNin mAP（mAP（クラウドゲートウェイ）（entityID:https://cg.gakunin.jp/idp/shibboleth）の証明書を使いSPにリクエストします。
SP側ではリクエストを受け取った際に、GakuNin mAPの証明書であることを確認してください。mAP（クラウドゲートウェイ）の証明書であることを確認してください。
また、mAP側はTLSサーバ証明書認証によりリクエスト先の正当性確認を行ないます。登録したURLのスキームがHTTPSであること、および当該URLのサーバ証明書がSPメタデータに記載されたものと一致することをご確認ください。
...