Fruizione API

In questa sezione vengono descritti i passi di configurazione necessari, ad un applicativo client interno al dominio di gestione, per poter fruire di una API REST esterna. L’API REST esterna utilizzata sarà lo Swagger Petstore e, poiché si suppone che lo scenario descritto nella sezione Erogazione API REST sia già stato provato, non è necessario registrare nuovamente l’API.

In GovWay ad ogni dominio, interno o esterno, viene associato ad un Soggetto. Nella sezione Modalità Multi-Tenant viene descritto come registrare più soggetti relativi a domini interni. In questo esempio, invece, procederemo con la registrazione di un soggetto esterno che rappresenta il gestore del dominio a cui appartiene il PetStore.

La fruizione di API, per questo primo esempio di utilizzo, viene registrata in modo che sia accessibile in forma anonima da qualunque client invocando l’url esposta da GovWay. Una rappresentazione di questo scenario è mostrata nella Fig. 956.

../../_images/fruizioneRESTBase.png

Fig. 956 Fruizione di una API tramite GovWay

Per registrare l’API su Govway, utilizzando la console govwayConsole, procedere come segue:

  1. Registrazione nuovo Soggetto del dominio esterno

    Accedere alla sezione “Soggetti” e selezionare il pulsante “Aggiungi”. Fornire i seguenti dati:

    • Dominio: selezionare la voce “Esterno”. Questa voce è presente solamente se il Multitenat è abilitato su GovWay (maggiori dettagli sono forniti nella sezione Modalità Multi-Tenant).

    • Nome: indicare il nome del Soggetto che rappresenta il nuovo dominio esterno, ad esempio “EnteEsterno”.

    • Tipologia: selezionare la voce “Erogatore”.

    • Descrizione: opzionalmente è possibile fornire una descrizione generica del soggetto.

    ../../_images/fruizioneRESTBaseRegistrazioneSoggetto.png

    Fig. 957 Registrazione nuovo Soggetto

  2. Registrazione Fruizione

    Accedere alla sezione “Fruizioni” e selezionare il pulsante “Aggiungi”. Fornire i seguenti dati:

    • API - Nome: selezionare l’API precedentemente registrata “PetStore v2”.

    • Soggetto Erogatore - Nome: selezionare il soggetto precedentemente registrato “EnteEsterno”.

    • Controllo degli Accessi - Accesso API: per esporre l’API in modo che sia invocabile da qualunque client in forma anonima selezionare lo stato “pubblico”.

    • Connettore - Endpoint: indicare la base uri dove viene erogata l’API nel dominio esterno. Per il nostro esempio utilizzare la url:

      • https://petstore.swagger.io/v2

      Nota

      Verifica del certificato server
      Per validare il certificato ritornato dal server “petstore.swagger.io” deve essere effettuata una opportuna configurazione del trustStore tls come descritto nella sezione Autenticazione Https. Poichè non è obiettivo di questo scenario si suggerisce di disabilitare la validazione del certificato server.

    ../../_images/fruizioneRESTBaseRegistrazioneFruizione.png

    Fig. 958 Registrazione di una fruizione di API

    Effettuato il salvataggio, l’API erogata sarà consultabile all’interno dell’elenco delle fruizioni. Accedendo al dettaglio si potrà conoscere l”url di invocazione che deve essere comunicata ai client che desiderano invocare l’API.

    ../../_images/fruizioneRESTBaseConsultazioneFruizione.png

    Fig. 959 URL di Invocazione dell’API fruita

  3. Invocazione API tramite GovWay

    Al termine di questi passi di configurazione il servizio REST sarà raggiungibile dai client utilizzando l’url di invocazione:

    Nota

    Soggetto Interno al Dominio

    In questo esempio si suppone che il nome del soggetto fornito durante la fase di installazione di GovWay sia Ente.

    curl -v -X PUT "http://127.0.0.1:8080/govway/out/Ente/EnteEsterno/PetStore/v1/pet" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{
        "id": 3,
        "category": { "id": 22, "name": "dog" },
        "name": "doggie",
        "photoUrls": [ "http://image/dog.jpg" ],
        "tags": [ { "id": 23, "name": "white" } ],
        "status": "available"
}'

    L’esito dell’aggiornamento viene confermato con un codice http 200 e una risposta json equivalente alla richiesta:

    HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
Content-Type: application/json
Transfer-Encoding: chunked
Server: GovWay
GovWay-Message-ID: 84e1d9a4-c181-436f-b7f0-4cabf55c370d
GovWay-Transaction-ID: 6c13b9ac-3d60-45a6-9130-297a4d832824

{
    "id":3,
    "category":{"id":22,"name":"dog"},
    "name":"doggie",
    "photoUrls":["http://image/dog.jpg"],
    "tags":[{"id":23,"name":"white"}],
    "status":"available"
}

  4. Consultazione Tracce

    Attraverso la console govwayMonitor è possibile consultare lo storico delle transazioni che sono transitate nel gateway e recuperare i dettagli di una singola invocazione cosi come già descritto nella sezione Erogazione API REST.