Lettura delle connessioni

Operazioni di lettura delle connessioni

Lettura di una singola connessione
Elencare connessioni
Model

Lettura di una singola connessione

API per recuperare i dati di una specifica connessione dato il suo ID

[GET] /api/v3/connections/{connectionId}

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Path Parameters

connectionId: identificativo univoco della connessione da leggere

Risposte

L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 200. Ogni altro codice di risposta indica uno stato di errore.

HTTP 200

La connessione è stata recuperata con successo.

Il body della risposta è un singolo Link contenente la sola connessione richiesta:

{
  "id": "string",
  "managerId": "string",
  "managedId": "string",
  "managerDescription": "string",
  "managedDescription": "string",
  "connections": [
    {
      "id": "string",
      "status": {
        "active": true,
        "activatedAt": "2020-09-10T13:49:33.092Z",
        "activatedBy": "string",
        "createdAt": "2020-09-10T13:49:33.092Z",
        "createdBy": "string",
        "modifiedAt": "2020-09-10T13:49:33.092Z",
        "modifiedBy": "string",
        "deleted": true,
        "deletedAt": "2020-09-10T13:49:33.092Z",
        "deletedBy": "string",
        "status": "string",
        "certificationStatus": "string"
      },
      "appId": "string",
      "featureCode": "string",
      "permission": "string",
      "approvalType": "string",
      "serviceId": "string"
    }
  ]
}

HTTP 400

Uno o più parametri forniti nella richiesta sono errati, o mancano dei parametri obbligatori.

HTTP 401

Il token autorizzativo è scaduto, invalido o non è stato specificato.

HTTP 403

Il token autorizzativo fornito è valido, ma l'utente non ha i permessi necessari a creare una connessione per il gestore specificato.

HTTP 500

Il server ha riscontrato un errore inaspettato nella creazione della richiesta di connessione

HTTP 502

Il server ha riscontrato un errore inaspettato nel comunicare con un servizio dal quale dipende per poter completare il processo (ad esempio, il servizio di auth non risulta essere disponibile)

Tutte le risposte d'errore condividono il seguente formato per il body di risposta:

{
  "code": "string",
  "message": "string",
  "status": "string",
  "subErrors": [
    {}
  ],
  "timestamp": "dd-MM-yyyy HH:mm:ss"
}

code: corrisponde al codice d'errore HTTP ritornato (es: 409)
message: messaggio d'errore (es: Impossibile creare una connessione gia' esistente)
status: descrizione a parole del codice d'errore HTTP (es: Conflict)
subErrors: eventuali errori innestati in quello ritornato
timestamp: data ed ora di ritorno dell'errore

Elencare connessioni

API che permettono di ottenere un elenco filtrato di link con le relative connessioni.

Sono disponibili 2 API per questo tipo di lettura, le quali si differenziano per i controlli autorizzativi effettuati e per il campo sul quale viene applicata la ricerca full text.

Ricerca dei gestori

[GET] /api/v3/connections/manager

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Query Parameters

Parametri obbligatori

page: numero della pagina da recuperare. La prima pagina è 0
size: numero di connessioni da recuperare per pagina

Parametri opzionali

active: booleano; se true, verranno ritornate le sole connessioni attive. Si consiglia di combinare active=true con deleted=false
appId: elenco separato da virgole di appId da ricercare
deleted: booleano; se true, vengono ritornate le sole connessioni che sono state eliminate
featureCode: elenco separato da virgole di featureCode da ricercare
fullText: effettua una ricerca fullText sulla ragione sociale del gestore della connessione
managedIds: elenco separato da virgole di itemId da ricercare come item gestito nella connessione. I controlli autorizzativi vengono effettuati su questo campo, ogni item per il quale l'utente attuale non ha i permessi necessari viene ignorato
managerIds: elenco separato da virgole di itemId da ricercare come item gestore nella connessione
status: elenco separato da virgole di Status
approvalTypes: elenco separato da virgole di CertificationStatus
unpaged: booleano; se true, ignora i parametri page e size e ritorna tutti i risultati in un singolo JSON di risposta

Effettuare una chiamata non paginata potrebbe ritornare una mole ingente di dati, si consiglia di evitarle a meno che non siano assolutamente necessarie

Risposte

L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 200. Ogni altro codice di risposta indica uno stato di errore.

HTTP 200

L'elenco di connessioni è stato recuperato con successo.

{
  "content": [
    {
      "id": "string",
      "managerId": "string",
      "managedId": "string",
      "managerDescription": "string",
      "managedDescription": "string",
      "connections": [
        {
          "id": "string",
          "status": {
            "active": true,
            "activatedAt": "2020-09-11T10:01:15.512Z",
            "activatedBy": "string",
            "createdAt": "2020-09-11T10:01:15.512Z",
            "createdBy": "string",
            "modifiedAt": "2020-09-11T10:01:15.512Z",
            "modifiedBy": "string",
            "deleted": true,
            "deletedAt": "2020-09-11T10:01:15.512Z",
            "deletedBy": "string",
            "status": "string",
            "certificationStatus": "string"
          },
          "appId": "string",
          "featureCode": "string",
          "permission": "string",
          "approvalType": "string",
          "serviceId": "string"
        }
      ]
    }
  ],
  "totalElements": 0,
  "totalPages": 0,
  "number": 0,
  "numberOfElements": 0,
  "size": 0
}

content: array di Link, ognuno dei quali contiene le sole connessioni che rispettano i filtri specificati. Se un Link è presente nella risposta, contiene almeno una connessione che rispetta i filtri.
totalElements: numero totale delle connessioni che rispettano i filtri specificati
totalPages: numero totale di pagine disponibili data la size specificata
number: numero di pagina attuale
numberOfElements: numero di elementi ritornati nella pagina
size: dimensione della pagina

HTTP 400

Uno o più parametri forniti nella richiesta sono errati, o mancano dei parametri obbligatori.

HTTP 401

Il token autorizzativo è scaduto, invalido o non è stato specificato.

HTTP 403

Il token autorizzativo fornito è valido, ma l'utente non ha i permessi necessari a creare una connessione per il gestore specificato.

HTTP 500

Il server ha riscontrato un errore inaspettato nella creazione della richiesta di connessione

HTTP 502

Il server ha riscontrato un errore inaspettato nel comunicare con un servizio dal quale dipende per poter completare il processo (ad esempio, il servizio di auth non risulta essere disponibile)

Tutte le risposte d'errore condividono il seguente formato per il body di risposta:

{
  "code": "string",
  "message": "string",
  "status": "string",
  "subErrors": [
    {}
  ],
  "timestamp": "dd-MM-yyyy HH:mm:ss"
}

code: corrisponde al codice d'errore HTTP ritornato (es: 500)
message: messaggio d'errore (es: Errore interno del server)
status: descrizione a parole del codice d'errore HTTP (es: Internal server error)
subErrors: eventuali errori innestati in quello ritornato
timestamp: data ed ora di ritorno dell'errore

Ricerca delle gestite

[GET] /api/v3/connections/managed

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Query Parameters

Parametri obbligatori

page: numero della pagina da recuperare. La prima pagina è 0
size: numero di connessioni da recuperare per pagina

Parametri opzionali

active: booleano; se true, verranno ritornate le sole connessioni attive. Si consiglia di combinare active=true con disabled=false
appId: elenco separato da virgole di appId da ricercare
deleted: booleano; se true, vengono ritornate le sole connessioni che sono state eliminate
featureCode: elenco separato da virgole di featureCode da ricercare
fullText: effettua una ricerca fullText sulla ragione sociale del gestore della connessione
managedIds: elenco separato da virgole di itemId da ricercare come item gestito nella connessione
managerIds: elenco separato da virgole di itemId da ricercare come item gestore nella connessione. I controlli autorizzativi vengono effettuati su questo campo, ogni item per il quale l'utente attuale non ha i permessi necessari viene ignorato
status: elenco separato da virgole di Status
approvalTypes: elenco separato da virgole di CertificationStatus
unpaged: booleano; se true, ignora i parametri page e size e ritorna tutti i risultati in un singolo JSON di risposta

Effettuare una chiamata non paginata potrebbe ritornare una mole ingente di dati, si consiglia di evitarle a meno che non siano assolutamente necessarie

Risposte

L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 200. Ogni altro codice di risposta indica uno stato di errore.

HTTP 200

L'elenco di connessioni è stato recuperato con successo.

{
  "content": [
    {
      "id": "string",
      "managerId": "string",
      "managedId": "string",
      "managerDescription": "string",
      "managedDescription": "string",
      "connections": [
        {
          "id": "string",
          "status": {
            "active": true,
            "activatedAt": "2020-09-11T10:01:15.512Z",
            "activatedBy": "string",
            "createdAt": "2020-09-11T10:01:15.512Z",
            "createdBy": "string",
            "modifiedAt": "2020-09-11T10:01:15.512Z",
            "modifiedBy": "string",
            "deleted": true,
            "deletedAt": "2020-09-11T10:01:15.512Z",
            "deletedBy": "string",
            "status": "string",
            "certificationStatus": "string"
          },
          "appId": "string",
          "featureCode": "string",
          "permission": "string",
          "approvalType": "string",
          "serviceId": "string"
        }
      ]
    }
  ],
  "totalElements": 0,
  "totalPages": 0,
  "number": 0,
  "numberOfElements": 0,
  "size": 0
}

content: array di Link, ognuno dei quali contiene le sole connessioni che rispettano i filtri specificati. Se un Link è presente nella risposta, contiene almeno una connessione che rispetta i filtri.
totalElements: numero totale delle connessioni che rispettano i filtri specificati
totalPages: numero totale di pagine disponibili data la size specificata
number: numero di pagina attuale
numberOfElements: numero di elementi ritornati nella pagina
size: dimensione della pagina

HTTP 400

Uno o più parametri forniti nella richiesta sono errati, o mancano dei parametri obbligatori.

HTTP 401

Il token autorizzativo è scaduto, invalido o non è stato specificato.

HTTP 403

Il token autorizzativo fornito è valido, ma l'utente non ha i permessi necessari a creare una connessione per il gestore specificato.

HTTP 500

Il server ha riscontrato un errore inaspettato nella creazione della richiesta di connessione

HTTP 502

Il server ha riscontrato un errore inaspettato nel comunicare con un servizio dal quale dipende per poter completare il processo (ad esempio, il servizio di auth non risulta essere disponibile)

Tutte le risposte d'errore condividono il seguente formato per il body di risposta:

{
  "code": "string",
  "message": "string",
  "status": "string",
  "subErrors": [
    {}
  ],
  "timestamp": "dd-MM-yyyy HH:mm:ss"
}

code: corrisponde al codice d'errore HTTP ritornato (es: 500)
message: messaggio d'errore (es: Errore interno del server)
status: descrizione a parole del codice d'errore HTTP (es: Internal server error)
subErrors: eventuali errori innestati in quello ritornato
timestamp: data ed ora di ritorno dell'errore

Model

Elenco dei model ritornati dalle API di lettura

Link

Un link è l'entità che indica il legame fra un item gestore e un item gestito. Contiene tutte le connessioni relative alla coppia di item.

{
  "id": "string",
  "managerId": "string",
  "managedId": "string",
  "managerDescription": "string",
  "managedDescription": "string",
  "connections": [...]
}

id: identificativo univoco della connessione
managerId: identificativo dell'item gestore della connessione
managedId: identificativo dell'item gestito nella connessione
managerDescription: ragione sociale dell'item gestore
managedDescription: ragione sociale dell'item gestito
connections: array contenente tutte le connessioni relative alla coppia gestore/gestita

Connection

Entità che esprime una connessione per uno specifico servizio

{
  "id": "string",
  "status": {
    "active": true,
    "activatedAt": "2020-09-10T14:30:22.575Z",
    "activatedBy": "string",
    "createdAt": "2020-09-10T14:30:22.575Z",
    "createdBy": "string",
    "modifiedAt": "2020-09-10T14:30:22.575Z",
    "modifiedBy": "string",
    "deleted": true,
    "deletedAt": "2020-09-10T14:30:22.575Z",
    "deletedBy": "string",
    "status": "string",
    "certificationStatus": "string"
  },
  "appId": "string",
  "featureCode": "string",
  "permission": "string",
  "approvalType": "string",
  "serviceId": "string"
}

id: identificativo univoco della connessione
status: informazioni sullo stato della connessione
- active: se true, la connessione è attiva ed utilizzabile
- activatedAt: data ed ora di attivazione della connessione espressa come stringa
- activatedBy: identificativo dell'utenza che ha creato la connessione
- createdAt: data ed ora di creazione della connessione espressa come stringa
- createdBy: identificativo dell'utenza che ha creato la connessione
- modifiedAt: data ed ora di ultima modifica della connessione, espressa come stringa
- modifiedBy: identificativo dell'utenza che ha modificato la connessione
- deleted: se true, la connessione è stata eliminata e non è più utilizzabile
- deletedAt: data di cancellazione della connessione, espressa come stringa
- deletedBy: identificativo dell'utenza che ha effettuato la cancellazione
- status: stato attuale della connessione. Per maggiori informazioni, vedi ConnectionStatus
- certificationStatus: stato di certificazione della connessione. Per maggiori informazioni, vedi CertificationStatus
appId: identificativo dell'applicazione a cui fa riferimento la connessione
featureCode: identificativo della feature dell'applicazione a cui fa riferimento la connessione. Se l'applicazione non ha multiple feature, il campo è null
permission: stringa che identifica il livello di permessi che la connessione fornisce al gestore. Valori possibili: READ, READ_WRITE
serviceId: identificativo del servizio al quale fa riferimento la connessione

ConnectionStatus

Enum che indica lo stato attuale di una connessione. I valori possibili sono:

PENDING_REQUEST: la connessione è in attesa di accettazione o rifiuto da parte di una gestita
REQUEST_REJECTED: la richiesta di connessione è stata rifiutata dalla gestita
UNVERIFIED: la connessione è correttamente attiva, ma non ha ottenuto alcun tipo di validazione
PENDING_VALIDATION: il gestore della connessione ha caricato un Atto d'Affidamento ed è ora in attesa che esso venga accettato o rifiutato
VALIDATION_REJECTED: l'Atto d'Affidamento caricato dal gestore è stato rifiutato, ed è quindi necessario procedere con l'upload di un nuovo AdA
VALIDATED: la connessione è in stato convalidato

CertificationStatus

Enum che indica lo stato di certificazione attuale di una connessione. I valori possibili sono:

AWAITING_UPLOAD: un AdA precedentemente caricato per la connessione è stato invalidato ed è quindi necessario procedere con un nuovo upload
AWAITING_APPROVAL: il gestore della connessione ha caricato un Atto d'Affidamento ed è ora in attesa che esso venga accettato o rifiutato
CERTIFIED: la connessione è stata correttamente certificata