italia / api-padigitale2026-misura1.3.1-uni-afam

Specifiche API relative alla misura 1.3.1 per l'avviso dedicato alle Università e AFAM
Creative Commons Zero v1.0 Universal
6 stars 4 forks source link

IFS04.2 e IFS05.2 - Dubbi su campo response_code della response #191

Closed AlessandroGualdaniUniGe closed 1 month ago

AlessandroGualdaniUniGe commented 1 month ago

Buonasera, negli schemi OpenAPI delle API IFS04.2 https://github.com/italia/api-padigitale2026-misura1.3.1-uni-afam/blob/main/src/IFS04-rettifica-iscrizioni.yaml e IFS05.2 https://github.com/italia/api-padigitale2026-misura1.3.1-uni-afam/blob/main/src/IFS05-rettifica-titoli.yaml l'attributo response_code della response risulta obbligatorio ma negli esempi di response https://github.com/italia/api-padigitale2026-misura1.3.1-uni-afam/blob/main/doc/03_analysis/io_schema/IFS04.2-response.json e https://github.com/italia/api-padigitale2026-misura1.3.1-uni-afam/blob/main/doc/03_analysis/io_schema/IFS05.2-response.json non è presente.

Inoltre, quale è il significato di response_code? Inoltre, c'è l'attributo file_status (che prevede 4 valori: approved, rejected, acquired, cancelled) mentre response_code ne prevede solo due (approved, rejected): come si combinano gli attributi ed in che modo vanno usati, restituendo i rispettivi valori?

Saluti.

Gualdani Alessandro

denismarini commented 1 month ago

Buonasera @AlessandroGualdaniUniGe,

L'errore nella json è un refuso e l'abbiamo corretto. Inoltre, di seguito il dettaglio sul significato dei campi:

response_code: Indica il codice di risposta generato dall'invocazione dell'API per le operazioni di inserimento o eliminazione (insert, delete). Questo codice riflette l'esito della validazione del payload, determinando se la transazione è approvata o rifiutata in base alla correttezza dei dati ricevuti. Si applica esclusivamente alle versioni 4.1 e 4.3, ovvero alle richieste di inserimento ed eliminazione.

file_status: Rappresenta lo stato del processo relativo alla richiesta di rettifica.

Per esempio se il respose_code è rejected nella richiesta di inserimento il file_status e il file_code dovrebbero essere null. Diversamente nella cancellazione se il la response_code è rejected il file_status e il file_code rimangono invariati.

Abbiamo quindi messo a nullable anche il file_status e il file_code ed abbiamo fatto degli esempi,

Stiamo ancora lavorando all'aggiornamento e prevediamo di completarlo entro il 25 luglio. Se hai domande o non ti è chiaro cosa stiamo facendo, scrivici e faremo del nostro meglio per chiarire e migliorare ulteriormente.

Mille grazie per questa segnalazione

cc @davidelongo-ey

AlessandroGualdaniUniGe commented 1 month ago

Buongiorno, grazie per il riscontro, ho ancora un dubbio su come utilizzare il response_code ovvero dal momento che riflette l'esito della validazione del payload (determinando se la transazione è approvata o rifiutata in base alla correttezza dei dati ricevuti), quando restituire HTTP 200 e response_code: rejected invece di HTTP 400 Bad Request?

Ad es. se nella request manca il tax_code (attributo obbligatorio) dobbiamo rispondere HTTP 400 Bad Request oppure HTTP 200 con response_code: rejected?

Secondo me, HTTP 400 Bad Request andrebbe usato se il payload non è sintatticamente corretto (es. attributo obbligatorio mancante, attributo che non rispetta un'espressione regolare, ecc.).

Invece, HTTP 200 con response_code: rejected andrebbe usato se il payload è sintatticamente corretto ma i dati in esso non lo sono (es. codice fiscale di uno studente inesistente, degree_course_code inesistente, ecc.).

L'interpretazione qui sopra è corretta?

Saluti.

Gualdani Alessandro

denismarini commented 1 month ago

@AlessandroGualdaniUniGe abbiamo aggiornato la descrizione sul readme.md con le tue osservazioni

https://github.com/italia/api-padigitale2026-misura1.3.1-uni-afam/tree/main#ifs04-rettifica-iscrizioni

https://github.com/italia/api-padigitale2026-misura1.3.1-uni-afam/tree/main#ifs05-rettifica-titoli

Mille grazie