メインコンテンツまでスキップ

2. リクエストパラメータ "authorization_details"

リクエストパラメータauthorization_detailsは、JSON表記法でオブジェクトの配列を含みます。各JSONオブジェクトには、特定のタイプのリソースの認可要件を指定するためのデータが含まれています。リソースまたはアクセス要件のタイプは、次のように定義されるtypeフィールドによって決定されます:

type: 文字列としての認可詳細タイプの識別子。typeフィールドの値は、それを含むオブジェクトの許容可能な内容を決定します。この値は、ASのコンテキストで記述されたAPIに対して一意です。このフィールドは必須(REQUIRED)です。

authorization_details配列には、同じタイプの複数のエントリが含まれる場合があります(MAY)。

図2は、上記の例データを使用したpayment_initiationタイプのauthorization_detailsを示しています:

[
  {
    "type": "payment_initiation",
    "actions": [
      "initiate",
      "status",
      "cancel"
    ],
    "locations": [
      "https://example.com/payments"
    ],
    "instructedAmount": {
      "currency": "EUR",
      "amount": "123.50"
    },
    "creditorName": "Merchant A",
    "creditorAccount": {
      "iban": "DE02100100109307118603"
    },
    "remittanceInformationUnstructured": "Ref Number Merchant"
  }
]

図3は、アカウント情報へのアクセスと支払いを開始する権限を求める組み合わせリクエストを示しています:

[
  {
    "type": "account_information",
    "actions": [
      "list_accounts",
      "read_balances",
      "read_transactions"
    ],
    "locations": [
      "https://example.com/accounts"
    ]
  },
  {
    "type": "payment_initiation",
    "actions": [
      "initiate",
      "status",
      "cancel"
    ],
    "locations": [
      "https://example.com/payments"
    ],
    "instructedAmount": {
      "currency": "EUR",
      "amount": "123.50"
    },
    "creditorName": "Merchant A",
    "creditorAccount": {
      "iban": "DE02100100109307118603"
    },
    "remittanceInformationUnstructured": "Ref Number Merchant"
  }
]

account_informationとpayment_initiationのtypeフィールドを持つJSONオブジェクトは、ASが同意を求めるために使用する異なる認可詳細を表します。

注意: ASは、このデータを後でそれぞれのRSに利用可能にします(セクション9を参照)。

2.1. 認可詳細タイプ (Authorization Details Types)​

ASは、typeパラメータの値の解釈およびtypeパラメータが許可するオブジェクトフィールドを制御します。ただし、typeパラメータの値も一般的に文書化され、開発者によって使用されることが意図されています。API設計者は、曖昧さなく簡単にコピーできるタイプ値を選択することが推奨されます(RECOMMENDED)。例えば、一部のグリフは同じ視覚文字に対して複数のUnicodeコードポイントを持ち、開発者はASが定義したものとは異なる文字を入力する可能性があります。潜在的な混乱を減らす可能な手段は、値をASCII[RFC0020]文字に制限すること、データタイプ値の機械可読リストを提供すること、または開発者にドキュメントから直接コピー&ペーストするように指示することです。

アプリケーションまたはAPIがオープン標準の場合のように異なるサーバー間でデプロイされることが予想される場合、API設計者は、API設計者が制御するURIなど、制御下の衝突耐性のある名前空間を使用することが推奨されます(RECOMMENDED)。

次の例は、実装が衝突耐性のあるタイプ値を確保するために名前空間https://scheme.example.org/をどのように利用できるかを示しています:

{
  "type": "https://scheme.example.org/files",
  "locations": [
    "https://example.com/files"
  ],
  "permissions": [
    {
      "path": "/myfiles/A",
      "access": [
        "read"
      ]
    },
    {
      "path": "/myfiles/A/X",
      "access": [
        "read",
        "write"
      ]
    }
  ]
}

2.2. 共通データフィールド (Common Data Fields)​

本仕様は、異なるタイプのAPI間で使用できるように設計された一連の共通データフィールドを定義しています。本仕様は、API定義によるこれらの共通フィールドの使用を要求せず、代わりに、API設計者が利用するための再利用可能な汎用コンポーネントとしてそれらを提供します。すべてのフィールドの許容値は、特定の"type"値によって定義された、保護されているAPIによって決定されます。

locations: リソースまたはRSの場所を表す文字列の配列。これらの文字列は通常、RSの場所を識別するURIです。このフィールドは、セクション12で説明されているように、クライアントが特定のRSを指定できるようにすることができます。

actions: リソースで実行されるアクションの種類を表す文字列の配列。

datatypes: リソースから要求されるデータの種類を表す文字列の配列。

identifier: APIで利用可能な特定のリソースを示す文字列識別子。

privileges: リソースで要求される特権のタイプまたはレベルを表す文字列の配列。

異なる共通データフィールドが組み合わせて使用される場合、クライアントが要求する権限はすべての値の積です。オブジェクトは、オブジェクト内にリストされているすべてのactions値が、オブジェクト内にリストされているすべてのlocations値で、オブジェクト内にリストされているすべてのdatatypes値に対して使用されることを要求します。

次の例では、クライアントはcustomer_information APIで顧客に属する連絡先と写真の両方への読み取りおよび書き込みアクセスを要求しています。このリクエストが許可された場合、クライアントは、写真への読み取りアクセスや連絡先への書き込みアクセスなど、APIによって定義された権利の任意の組み合わせを使用できると想定します。

[
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "read",
      "write"
    ],
    "datatypes": [
      "contacts",
      "photos"
    ]
  }
]

クライアントがアクセスをより細かく制御したい場合は、複数のオブジェクトを送信できます。この例では、クライアントは同じAPIエンドポイントで連絡先への読み取りアクセスと写真への書き込みアクセスを求めています。このリクエストが許可された場合、クライアントは連絡先に書き込むことはできません。

[
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "read"
    ],
    "datatypes": [
      "contacts"
    ]
  },
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "write"
    ],
    "datatypes": [
      "photos"
    ]
  }
]

APIは、それぞれの認可オブジェクトのタイプに応じて、独自の拡張を定義する場合があります(MAY)。API設計者は、本仕様で定義された共通データフィールドとAPI自体に固有のフィールドの組み合わせを使用することが予想されます。

に最終更新