2. Parametro di Richiesta "authorization_details"

Il parametro di richiesta authorization_details contiene, in notazione JSON, un array di oggetti. Ogni oggetto JSON contiene i dati per specificare i requisiti di autorizzazione per un certo tipo di risorsa. Il tipo di risorsa o requisito di accesso è determinato dal campo type, che è definito come segue:

type: Un identificatore per il tipo di dettagli di autorizzazione come stringa. Il valore del campo type determina il contenuto consentito dell'oggetto che lo contiene. Il valore è unico per l'API descritta nel contesto dell'AS. Questo campo è OBBLIGATORIO (REQUIRED).

Un array authorization_details PUÒ contenere più voci dello stesso tipo.

La figura 2 mostra un authorization_details di tipo payment_initiation utilizzando i dati di esempio sopra indicati:

[
  {
    "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"
  }
]

La figura 3 mostra una richiesta combinata che chiede l'accesso alle informazioni dell'account e il permesso di avviare un pagamento:

[
  {
    "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"
  }
]

Gli oggetti JSON con campi di tipo account_information e payment_initiation rappresentano i diversi dettagli di autorizzazione da utilizzare dall'AS per richiedere il consenso.

Nota: L'AS renderà questi dati successivamente disponibili ai rispettivi RS (vedere Sezione 9).

2.1. Tipi di Dettagli di Autorizzazione (Authorization Details Types)

L'AS controlla l'interpretazione del valore del parametro type così come i campi dell'oggetto che il parametro type consente. Tuttavia, il valore del parametro type è anche generalmente documentato e destinato ad essere utilizzato dagli sviluppatori. Si RACCOMANDA (RECOMMENDED) che i progettisti di API scelgano valori di tipo facilmente copiabili senza ambiguità. Ad esempio, alcuni glifi hanno più punti di codice Unicode per lo stesso carattere visivo, e uno sviluppatore potrebbe potenzialmente digitare un carattere diverso da quello definito dall'AS. Possibili mezzi per ridurre la potenziale confusione sono limitare il valore ai caratteri ASCII [RFC0020], fornire un elenco leggibile dalla macchina dei valori del tipo di dati, o istruire gli sviluppatori a copiare e incollare direttamente dalla documentazione.

Se si prevede che un'applicazione o un'API venga distribuita su server diversi, come nel caso di uno standard aperto, si RACCOMANDA (RECOMMENDED) al progettista dell'API di utilizzare uno spazio dei nomi resistente alle collisioni sotto il loro controllo, come un URI che il progettista dell'API controlla.

L'esempio seguente mostra come un'implementazione potrebbe utilizzare lo spazio dei nomi https://scheme.example.org/ per garantire valori di tipo resistenti alle collisioni:

{
  "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. Campi di Dati Comuni (Common Data Fields)

Questa specifica definisce un insieme di campi di dati comuni progettati per essere utilizzabili tra diversi tipi di API. Questa specifica non richiede l'uso di questi campi comuni da parte di una definizione API ma, invece, li fornisce come componenti generici riutilizzabili che i progettisti di API possono utilizzare. I valori consentiti di tutti i campi sono determinati dall'API protetta, come definito da un particolare valore "type".

locations: Un array di stringhe che rappresentano la posizione della risorsa o dell'RS. Queste stringhe sono tipicamente URI che identificano la posizione dell'RS. Questo campo può consentire a un client di specificare un RS particolare, come discusso nella Sezione 12.

actions: Un array di stringhe che rappresentano i tipi di azioni da intraprendere sulla risorsa.

datatypes: Un array di stringhe che rappresentano i tipi di dati richiesti dalla risorsa.

identifier: Un identificatore di stringa che indica una risorsa specifica disponibile all'API.

privileges: Un array di stringhe che rappresentano i tipi o livelli di privilegio richiesti sulla risorsa.

Quando diversi campi di dati comuni vengono utilizzati in combinazione, le autorizzazioni richieste dal client sono il prodotto di tutti i valori. L'oggetto rappresenta una richiesta per tutti i valori actions elencati all'interno dell'oggetto da utilizzare in tutte le posizioni locations elencate all'interno dell'oggetto per tutti i valori datatypes elencati all'interno dell'oggetto.

Nell'esempio seguente, il client richiede l'accesso in lettura e scrittura sia ai contatti che alle foto appartenenti ai clienti in un'API customer_information. Se questa richiesta viene concessa, il client assumerebbe di essere in grado di utilizzare qualsiasi combinazione di diritti definiti dall'API, come l'accesso in lettura alle foto e l'accesso in scrittura ai contatti.

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

Se il client desidera avere un controllo più fine sul suo accesso, può inviare più oggetti. In questo esempio, il client sta chiedendo l'accesso in lettura ai contatti e l'accesso in scrittura alle foto nello stesso endpoint API. Se questa richiesta viene concessa, il client non sarebbe in grado di scrivere sui contatti.

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

Un'API PUÒ definire le proprie estensioni, soggette al tipo del rispettivo oggetto di autorizzazione. Si prevede che i progettisti di API utilizzeranno una combinazione di campi di dati comuni definiti in questa specifica così come campi specifici dell'API stessa.