Comuni-Chiamo OpenAPI V1 to V2 Migration Guide

Ultima release: 2.1.1

La seguente guida è un aiuto per migrare alla versione V2 dell’integrazione con Comuni-Chiamo. Questa nuova versione rispetta è conforme alla specifica OpenAPI ed alle Linee Guida sull’interoperabilità tecnica delle Pubbliche Amministrazioni.

Migration checklist per gli sviluppatori

  • verifica quali endpoint V1 vengono usati dalla tua integrazione e migrali alla V2 sfruttando il V1 → V2 mapping;
  • aggiorna la gestione degli errori con il nuovo formato usato dalla V2 come descritto nel paragrafo sulla Gestione degli errori;
  • testa l’implementazione della V2 con l’ambiente di staging prima di andare in produzione.

Endpoints: V1 → V2 mapping

Qui sotto troverete un mapping dalla precedente versione V1 alla nuova V2. Tutti gli endpoint della V1 sono elencati nella colonna di sinistra mentre nella colonna di destra troverete il loro equivalente per la V2. In alcuni endpoint cambierà soltanto il naming usato, mentre in altri potrebbero cambiare anche i parametri in input o la risposta restituita. Assicuratevi di avere mappato correttamente tutti gli aspetti degli endpoint che state utilizzando.

Dominio

Innanzitutto assicurarsi che il dominio delle richieste sia uno tra:

Dizionari

Tutti gli endpoint sono stati adeguati alla regola: 5.2.2 Usare parole separate da trattino per i path (kebab-case).

v1 v2
GET /dictionaries/issue_statuses GET /dictionaries/issue-statuses
GET /dictionaries/issue_alerts GET /dictionaries/issue-alerts
GET /dictionaries/outcome_values GET /dictionaries/outcome-values
GET /dictionaries/icon_ids GET /dictionaries/icon-ids
GET /dictionaries/geometry_types GET /dictionaries/geometry-types
GET /dictionaries/publication_statuses GET /dictionaries/publication-statuses

Mappe

v1 v2
POST /entities/{entity_id}/maps/{map_id}/pois/+{poi_id}
POST /entities/{entity_id}/maps/{map_id}/pois/-{poi_id}
PUT /entities/{entity_id}/maps/{map_id}/pois/{poi_id}/add
PUT /entities/{entity_id}/maps/{map_id}/pois/{poi_id}/remove
Al posto di usare + e - come indicatori, abbiamo deciso di rendere l’azione più esplicita specificando le due possibili azioni add e remove.
Inoltre al posto di utilizzare una POST è necessario utilizzare una richiesta PUT per questo endpoint.

Aggiornamento segnalazioni

v1 v2
POST /entities/{entity_id}/issues/{issue_id}/assigned_users/+{user_id}
POST /entities/{entity_id}/issues/{issue_id}/assigned_users/-{user_id}
PUT /entities/{entity_id}/issues/{issue_id}/assigned-users/{user_id}/add
PUT /entities/{entity_id}/issues/{issue_id}/assigned-users/{user_id}/remove
Come per le mappe, al posto di usare + e - come indicatori abbiamo deciso di rendere l’azione più esplicita specificando le due possibili azioni add e remove ed abbiamo deciso di utilizzare PUT al posto della richiestaPOST.
Infine abbiamo sostituito l’underscore che c’era in assigned-users come indicato dalla regola 5.2.2.
POST /entities/{entity_id}/issues/{issue_id}/outcome_value/{value}
POST /entities/{entity_id}/issues/{issue_id}/outcome-value/{value}
Sostituito l’underscore come indicato dalla regola 5.2.2.

Dettaglio segnalazione

v1 v2
GET /entities/{entity_id}/issues/{issue_id}
GET /entities/{entity_id}/issues/{issue_id}
L’endpoint è rimasto uguale, l’unica modifica fatta è nel payload di risposta.
La key "cf" utilizzata per le informazioni sui campi personalizzati opzionali che sono stati eventualmente configurati in questa segnalazione è stata trasformata in "cfs" dato che è una lista di informazioni (come da regola 4.3.1).

Creazione segnalazione

v1 v2
POST /entities/{entity_id}/report/add
POST /entities/{entity_id}/reports/add
Piccolissima modifica nel naming dell’endpoint con l’aggiunta della s finale in /reports.
Nel payload è stato aggiunto il parametro booleano has_notification_over_email che permette di accendere / spegnere la ricezione degli aggiornamenti sulla segnalazione direttamente nell’email indicata come segnalatore. Di default il valore è false, quindi la email sono disabilitate.

CRM

v1 v2
GET /entities/{entity_id}/crm/users/{crm_email} DEPRECATO
Questo endpoint è stato deprecato in quanto passare delle email in chiaro nella chiamata GET non è compliant con le normative in tema privacy

Gestione degli errori

Nella V2 gli errori sono stati tutti mappati usando la specifica RFC 7807 come indicato dalla regola: 5.2.8 Usare lo schema Problem JSON per le risposte di errore. In caso di errore il JSON avrà quindi il seguente formato: 

{
    "type": "https://openapi.comuni-chiamo.com/api/v2/docs/errors#type503",
    "instance": "https://openapi.comuni-chiamo.com/api/v2/docs/errors#type503_instanceStatus",
    "title": "Service Unavailable",
    "detail": "Sembra che il servizio di integrazione Comuni-Chiamo non sia attivo al momento. Il servizio potrebbe essere in manutenzione oppure potrebbe esserci un problema tecnico. Se il problema persiste, contatta il supporto tecnico.",
    "status": 503
}

Oltre a questi 5 parametri che saranno sempre presenti nel payload di errore potranno esserci altri parametri extra in base all’endpoint chiamato, utili per dare maggiori informazioni sull’errore o su come risolverlo. I parametri extra sono tutti documentati nella documentazione dei relativi endpoint.

Nota

Ad oggi non tutti gli errori sono stati mappati, se trovate dei link con errori non mappati informate Matteo Buferli [matteo.buferli@comuni-chiamo.com] e/o Davide Marchi [davide.marchi@comuni-chiamo.com], grazie.

Stato del servizio

Come da indicazioni 5.2.11 Esporre lo stato del servizio è presente l’endpoint /status che ritorna un HTTP status 200 OK se il servizio sta funzionando correttamente.