Open ioggstream opened 5 years ago
nardil
commented
5 years ago 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?
ioggstream
commented
5 years ago 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:
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 https://github.com/Kong/kong/pull/3451 Altri api gateway possono riprendere quel lavoro.
Se avete domande sono a disposizione.
nardil
commented
5 years ago 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 PUTNella 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 422Nell'attuale implementazione delle api GovPay abbiamo distinto cosi i possibili errori nella richiesta:
Ti risultano interpretazioni corrette?
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.
ioggstream
commented
5 years ago 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.
ioggstream
commented
5 years ago 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?
ioggstream
commented
5 years ago 3- sui codici di errore, vedo asap e ti dico. Se non rispondo entro lunedì mattina chiamami pure.
nardil
commented
5 years ago 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/RSSMRO80P19D612Moppure così
POST /cittadini
{
"codice_fiscale": "RSSMRO80P19D612M",
"nome": "mario",
"cognome": "rossi"
}
HTTP 201 Created
Location: http://..../cittadini/RSSMRO80P19D612MNon c'è una preferenza, valutate in base alla logica applicativa e alla manutenibilità.
Due note off-topic:
nome_proprio e non nome;/cittadino poiché ritornano una sola entry;ioggstream
commented
5 years ago Sugli errori:
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?
andreapoli
commented
5 years ago
- le richieste dovrebbero avere path al singolare
/cittadinopoiché 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:
ioggstream
commented
5 years ago @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?
tflagella
commented
5 years ago @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.
Ciao!
Vi segnalo i primi due capitoli del modello di interoperabilità in consultazione.
https://lg-modellointeroperabilita.readthedocs.io/it/latest/doc/doc_02_cap_04.html#
Il formato di errore indicato è problem+json, differente da faultBean.
C'è anche un lavoro di standardizzazione dei parametri di paginazione (limit, offset, ..)
Qui trovate alcune un post iniziale con delle API di esempio: ovviamente sono benvenuti suggerimenti e contributi poiché il lavoro sull'interoperabilità continua!