Comments (12)
Ciao @ioggstream ,
grazie per la segnalazione! Analizzeremo il modello di interoperabilità per adeguare i servizi alle linee guida. Non mancheremo a dare il nostro contributo.
E' il Forum Italia, sezione interoperabilità il posto giusto per farlo?
from govpay.
Ciao Lorenzo,
-
la consultazione sui primi due capitoli si è chiusa a giugno, ma dovrebbe essere sempre possibile commentare qui: https://forum.italia.it/c/documenti-in-consultazione/linee-guida-modello-di-interoperabilita
-
commenti, issue e soprattutto PR via github sono più che benvenuti: https://github.com/italia/lg-modellointeroperabilita-docs sebbene le PR:
- sono promemoria per il prosieguo del lavoro;
- non vengono mergiate, a meno che non correggano refusi;
- i punti 1 e 2 non escludono che possano effettivamente essere mergiate durante il rilascio
del capitolo 3 ;)
-
a breve dovremmo mettere in consultazione il capitolo 3 con il dettaglio delle specifiche tecniche su REST e SOAP. Il cap.3 esplicita buona parte delle indicazioni che già trovi sopra
-
in particolare vi può interessare il sistema obbligatorio di rate-limiting e throttling https://forum.italia.it/t/header-standardizzati-per-un-ecosistema-api-affidabile/3166 . Ho implementato una POC su kong Kong/kong#3451 Altri api gateway possono riprendere quel lavoro.
Se avete domande sono a disposizione.
from govpay.
Ciao @ioggstream ,
stiamo lavorando per adeguare le api di GovPay alle specifiche di interoperabilita', ma abbiamo qualche dubbio su alcune scelte fatte che potremmo rivedere in questa fase:
POST
vs PUT
Nella nostra attuale implementazione abbiamo assunto che la PUT
sia idempotente, mentre la POST
crea nuove risorse ad ogni chiamata. Pertanto la PUT /pendenze/12345
crea (HTTP 201) o aggiorna (HTTP 200/204) la pendenza 12345
e reiterare la richiesta porta il server sempre al medesimo stato, a meno di errori. Di contro la POST /pagamenti
avvia una nuova transazione di pagamento e reiterare la richiesta risulta in nuove entità pagamento
sul server.
In rete il l'argomento è dibattuto e alcune argomentazioni supportano questa visione. Analizzando invece il servizio petstore di swagger risulta proposta una scelta diversa dalla nostra dove per inserire un pet
, equivalente alla nostra pendenza, viene usata la POST
.
Quale principio suggerisci di seguire in questa scelta?
400
vs 401
vs 403
vs 409
vs 422
Nell'attuale implementazione delle api GovPay abbiamo distinto cosi i possibili errori nella richiesta:
- 400: richiesta sintatticamente non valida rispetto alla specifica OpenAPI del servizio chiamato
- 401: la richiesta richiede l'autenticazione dell'utente chiamante
- 403: l'utente identificato non è autorizzato alla richiesta
- 409: richiesta valida sintatticamente, ma lo stato della risorsa non consente la sua esecuzione. Ad esempio annullare o aggiornare una pendenza già pagata.
- 422: richiesta valida sintatticamente, ma non semanticamente. Ad esempio la richiesta di inserire una pendenza il cui importo totale non corrisponde alla somma delle singole voci.
Ti risultano interpretazioni corrette?
URL alle risorse
E' corretto fornire come riferimento alle risorse la URI relativa con PATH assoluto, come ad esempio '/pendenze/12345'
?
Te lo chiedo perchè per quanto sarebbe preferibile la URI assoluta 'https://....'
, è talvolta impossibile, a livello applicativo, sapere il path di una risorsa, ad esempio accedendola da internet piuttosto che da intranet.
from govpay.
1- Put vs post: la scelta dipende dalla funzionalità/logica applicativa.
La PUT lascia al client la scelta dell'url della risorsa da creare. Ad esempio se creo una entry identificata dal cosice_fiscale già so qual è l'URL.
La POST lascia al server l'individuazione dell'url della risorsa creata, e lo ritorna tramite header OR payload.ad esempio quando creo un utente è il server che ritorna l'userid.
from govpay.
2- l'uso di uri relative nei payload delega al client la ricomposizione dell'uri finale e potrebbe avere dei limiti se le richieste devono essere firmate (eg. Il path relativo è questo, ma il serve qual era?)
Solitamente è possibile definire una variabile col "public URL" che dovrebbe essere già nell'openapi.yaml.
Capisco che la cosa possa essere noiosa, vi porta a duplicare del codice?
from govpay.
3- sui codici di errore, vedo asap e ti dico. Se non rispondo entro lunedì mattina chiamami pure.
from govpay.
1- Put vs post: la scelta dipende dalla funzionalità/logica applicativa.
La PUT lascia al client la scelta dell'url della risorsa da creare. Ad esempio se creo una entry identificata dal cosice_fiscale già so qual è l'URL.
La POST lascia al server l'individuazione dell'url della risorsa creata, e lo ritorna tramite header OR payload.ad esempio quando creo un utente è il server che ritorna l'userid.
Siamo in linea, ma c'è una preferenza tra i due approcci quando sono entrambi possibili?
PUT /cittadini/RSSMRO80P19D612M
{
"nome": "mario",
"cognome": "rossi"
}
HTTP 201 Created
Location: http://..../cittadini/RSSMRO80P19D612M
oppure così
POST /cittadini
{
"codice_fiscale": "RSSMRO80P19D612M",
"nome": "mario",
"cognome": "rossi"
}
HTTP 201 Created
Location: http://..../cittadini/RSSMRO80P19D612M
from govpay.
Non c'è una preferenza, valutate in base alla logica applicativa e alla manutenibilità.
Due note off-topic:
- il campo definito dall'ontologia è
nome_proprio
e nonnome
; - le richieste dovrebbero avere path al singolare
/cittadino
poiché ritornano una sola entry; - le richieste che tornano array dovrebbero avere path al plurale.
from govpay.
Sugli errori:
- puoi fare sempre riferimento a https://developer.mozilla.org/en-US/docs/Web/HTTP/Status (come sicuramente hai già fatto)
- 422 è definita in webdav https://tools.ietf.org/html/rfc4918#section-11.2. Usarla al di fuori potrebbe essere visto come un hijacking ;) Ti consiglierei di chiedere un parere su [email protected].
Considerato che 401, 403, 429 e 503 hanno una semantica universalmente definita, per gli altri è fondamentale usare bene problem+json
per aiutare lo sviluppatore del client a capire cos'è andato storto.
Ti torna tutto?
from govpay.
- le richieste dovrebbero avere path al singolare
/cittadino
poiché ritornano una sola entry;
Ciao @ioggstream ,
questa nota è derivata da qualche standard?
Te lo chiedo poichè varie api utilizzano sempre il path al plurale anche quando restituiscono (GET) o creano (POST/PUT) una singola entry.
Un esempio è il petstore fornito come esempio da openapi stesso:
- https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml
Altri esempi sono i seguenti servizi di google: - https://developers.google.com/drive/api/v3/reference/ (es. Files)
- https://developers.google.com/calendar/v3/reference/ (es. Events)
from govpay.
@andreapoli molte linee guida indicano l'utilizzo del solo plurale.
Noi volevamo anche un modo che permettesse di separare in maniera facile - anche architetturalmente - i path destinati alle entry e quelli destinati alle collezioni: questo per spingere anche gli erogatori a porsi delle domande "architetturali".
In questo modo ad esempio se il path è plurale potresti già sapere che si tratta eg. di una ricerca e redirigere su un backend "giusto".
Voi vedete delle controindicazioni?
from govpay.
@ioggstream a parte il fatto di discostarsi dalle comuni convenzioni, che già di per se non sembra una buona idea, mi pare che questa proposta si discosti anche dallo spirito dell'architettura REST, che tende a mutuare in toto l'esperienza del web. Se pensiamo ad esempio ad una API implementata nativamente tramite la root directory di un web server, non potrebbe esserci nessuna differenza nel path di base tra la collezione di oggetti e il singolo oggetto. Ad esempio per una root directory del tipo:
sample-api/
├── cittadini
│ ├── bianchi
│ ├── rossi
│ └── verdi
└── imprese
├── amazon
├── google
└── redhat
In un caso del genere, una:
GET /sample-api/cittadino/rossi
restituirebbe certamente un sano "404 Not Found".
Ovviamente si potrebbe ovviare in tanti modi, ma non sarebbe certamente nello spirito del web.
from govpay.
Related Issues (20)
- govpay su mysql/MariaDB in configurazione MASTER/SLAVE HOT 5
- Diciture dell'Attestazione di Pagamento non conformi alle SANP HOT 4
- Visualizzare anche le pendenze spontanee non pagate HOT 3
- Supporto alle stampe in formato PDF/A-1
- Filtro per data tracciato APK errato
- Numero avviso e IUV non generati alla creazione di una nuova pendenza di tipo Marca da Bollo HOT 2
- Exception handshake Mysql - Problemi di connesione MySQL HOT 2
- Update sql per aggiornamento minor version non completamente funzionanti HOT 3
- Pagamento POS NEXI HOT 1
- Pagamento Marca da Bollo Telematica su Modello di Pagamento Unico
- Autenticazione a pagoPA via Subscription Key HOT 2
- Elenco Ruoli non visualizzato correttamente
- Autoregistrazione degli Operatori autenticati
- API che espongono i datiPagoPA HOT 8
- Batch Tracciati non riprende correttamente elaborazione tracciati in stato 'IN_STAMPA'
- Popolare i metadata v2 con i dati contabili
- PKIX path building failed: - unable to find valid certification path to requested target HOT 10
- upgrade govpay da 3.4.2 a 3.6.2 HOT 7
- Errata definizione del campo prossimiRisultati
- Errore connessione da PagoPA a govpay (PPT_STAZIONE_INT_PA_IRRAGGIUNGIBILE) HOT 17
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from govpay.