Conformità alle specifiche di interoperabilità

[ioggstream]

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!

• https://forum.italia.it/t/creare-api-interoperabili-dove-partire/3491/4
• https://forum.italia.it/search?q=category%3A12%20%40Roberto_Polli

[nardil]

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]

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:

  1. sono promemoria per il prosieguo del lavoro;
  2. non vengono mergiate, a meno che non correggano refusi;
  3. 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 https://github.com/Kong/kong/pull/3451 Altri api gateway possono riprendere quel lavoro.

Se avete domande sono a disposizione.

[nardil]

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.

[ioggstream]

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]

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]

3- sui codici di errore, vedo asap e ti dico. Se non rispondo entro lunedì mattina chiamami pure.

[nardil]

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

[ioggstream]

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 non nome;
• le richieste dovrebbero avere path al singolare /cittadino poiché ritornano una sola entry;
• le richieste che tornano array dovrebbero avere path al plurale.

[ioggstream]

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?

[andreapoli]

• 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)

[ioggstream]

@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]

@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.