Implementare un'interfaccia API personalizzata per un servizio REST Faao

Quando si sviluppa un'applicazione per sistemi portatili, in genere si avvia con il layer dell'interfaccia utente e quindi si connette l'applicazione con un'altra applicazione utilizzando i servizi Web REST. Questo approccio funziona bene per applicazioni di piccole o semplici. Se le applicazioni sono più grandi e si desidera stabilire una connessione a più servizi backend, è possibile introdurre involontariamente problemi di prestazioni e sicurezza.

Si consiglia di iniziare a creare un layer API di aspetto tra i servizi backend esterni e l'interfaccia utente per ridurre il numero di chiamate ai servizi backend, ove possibile. Ad esempio, l'applicazione Mobile in uso può eseguire una singola chiamata al layer API fa> ade che gestisce le chiamate ad altri servizi REST e consolida tutti i dati in entrata in una singola risposta all'applicazione Mobile.

Crea un'interfaccia API personalizzata completa

Per creare un'interfaccia API personalizzata completa utilizzando Oracle Mobile Hub.

Fare clic su e selezionare Sviluppo, quindi selezionare API dal menu laterale. Se un'interfaccia API è già stata creata (in stato Bozza o Pubblicato), verrà visualizzato un elenco di interfacce API. Se non esiste alcuna interfaccia API personalizzata, verrà visualizzata una pagina con il pulsante Nuova interfaccia API. Fare clic sull'API già creata oppure fare clic su Nuova API per iniziare.

Definisci endpoint

Le risorse vengono create per definire gli endpoint dell'interfaccia API. Una risorsa è l'ambiente crux di un'interfaccia API. Dispone di un tipo, di alcuni dati associati, di una relazione con altre risorse e contiene uno o più metodi su cui agiscono. Una risorsa può essere quasi nulla: un'immagine, un file di testo, una raccolta di altre risorse, una transazione logica, una procedura e così via.

Fare clic sul collegamento di navigazione Endpoint per iniziare.
Fare clic su Nuova risorsa e aggiungere alcune informazioni di base.

Ogni volta che si fa clic su Nuova risorsa, viene creata una risorsa di livello superiore (radice). Se si desidera aggiungere una risorsa figlio (nidificata), fare clic su Aggiungi ( + ) accanto alla risorsa di livello superiore. Fare clic su X per eliminare una risorsa.

Nota:
Vedere le icone sotto i collegamenti Metodi? Ogni volta che si definisce un metodo per una risorsa, nel collegamento Metodi viene visualizzata un'icona. Utilizzarli come collegamenti per visualizzare i metodi già definiti per una risorsa. Fare clic su un'icona per passare direttamente alla relativa definizione nella pagina Metodi.
Fornire il percorso della risorsa, che è l'URI (relativo all'URI di base). Ad esempio, se l'URI di base è /mobile/custom/audits/, è possibile aggiungere la risorsa findings, ovvero /mobile/custom/audits/findings.
Fornire il nome visualizzato, ossia il nome della risorsa che facilita l'identificazione nella documentazione API.
Le risorse sono elencate in base ai relativi nomi visualizzati sul lato sinistro della pagina Test API.
Fornire una breve descrizione della risorsa.

Dopo aver immesso una descrizione, l'URI viene visualizzato sotto il campo della descrizione.
(Facoltativo) Fornire un tipo di risorsa RAML, ovvero il tipo di risorsa (resourcesType:). Non è necessario specificare un tipo di risorsa. Se si desidera utilizzare un tipo di risorsa ma non ne è stato definito uno, fare clic sul collegamento Tipi e definirne uno.

Quando si crea un metodo per una risorsa, sotto il collegamento Metodi viene visualizzato un simbolo per tale metodo. È possibile visualizzare immediatamente i metodi definiti per una risorsa se è necessario esaminare una definizione di risorsa. Fare clic su un'icona per passare direttamente alla definizione del metodo corrispondente.

È possibile cancellare il contenuto di una risorsa in modo più rapido passando alla modalità compatta (a destra di Nuova risorsa ). La visualizzazione compatta nasconde la descrizione della risorsa, il tipo di risorsa e il percorso.

Aggiungere metodi alle risorse

I metodi sono azioni che possono essere eseguite su una risorsa. La pagina Metodi mostra un metodo alla volta. Dopo aver definito almeno due metodi, è possibile fare clic sull'icona di un metodo nella parte superiore della pagina per visualizzarne i dettagli.

Aggiungere alcuni metodi alla risorsa facendo clic su Metodi.

Se la risorsa per cui si stanno definendo i metodi dispone di parametri di percorso, vengono visualizzati al di sopra di Aggiungi metodo.
1. (Facoltativo) Fare clic su Obbligatorio se si desidera che i parametri di percorso vengano passati con ogni metodo.
  Viene visualizzato il nome del parametro.
2. Fornire un nome visualizzato per il parametro e il codice di esempio.
3. Nell'elenco a discesa selezionare il tipo di valore valido per il parametro.
Fare clic su Aggiungi metodo e selezionare il metodo desiderato.

Dopo aver selezionato un metodo, non è più elencato nella lista di metodi perché si utilizza un metodo una sola volta per risorsa (ad esempio, non è possibile definire due metodi DELETE per una singola risorsa). Nella parte superiore della pagina viene visualizzata un'icona per ogni metodo definito. Fare clic su un'icona di metodo per passare direttamente alla relativa definizione.
(Facoltativo) Immettere una breve descrizione del metodo nel campo Descrizione.
(Facoltativo) Immettere un nome visualizzato per il metodo.
(Facoltativo) Fornire le caratteristiche da applicare al metodo.

Se non si dispone di caratteristiche definite, fare clic su Endpoint per tornare alla pagina Risorse principale e fare clic sul collegamento Traits per definirne uno. Consente di definire una raccolta di operazioni simili.

Dopo aver definito i metodi per la risorsa, è possibile definire le richieste e le risposte per tali metodi.

Definisci una richiesta per il metodo

Dopo aver selezionato un metodo, definire la richiesta di servizio a cui si desidera connettersi. Ad esempio, se è stato selezionato un metodo POST, ora è possibile definire cosa creare. A tale scopo, aggiungere parametri e un corpo della richiesta contenente la descrizione dei dati da inviare al servizio.

Fare clic su Richiesta per definire una richiesta.
Fare clic su Aggiungi parametro e selezionare un tipo di parametro: Query o Intestazione. Selezionare Obbligatorio se il parametro è obbligatorio per il metodo.
1. Assegnare un nome e un nome visualizzato al parametro.
2. Selezionare un tipo di valore valido: Stringa, Numero, Numero intero, Data o Booleano.
3. (Facoltativo) Fornire una descrizione del parametro e un esempio da utilizzare quando si esegue il test della validità dell'endpoint. Ad esempio, è possibile disporre di una risorsa audits e aggiungere un parametro di query auditorID che utilizzi un valore numerico e un altro parametro auditName, che accetta un valore stringa:
```
/audits: 
  get: 
    description: | 
      Gets list of audits, organizations etc.     
    queryParameters: 
      auditorID:  
        id: Auditor ID
        description: | 
          display auditor identifier 
        type: integer 
        example: |
          1234
        required: false      
      auditName:
        displayName: auditName
        description: |
          Audit name
        example: "Payroll Process Audit"
```
  In questo esempio, viene definito un metodo GET con i parametri di query auditorID e auditName.
4. (Facoltativo) Fare clic su Altre proprietà per aggiungere proprietà nidificate al parametro. Fare clic su Ripeti per aggiungere più elementi del parametro corrente.
5. Fare clic su Aggiungi parametro per aggiungere un altro parametro di livello superiore per il metodo.
A seconda del metodo selezionato, fare clic su Aggiungi tipo di supporto e definire il corpo del metodo. Il corpo contiene i dati inviati al server. Ad esempio, se si sta definendo un metodo POST, sarà necessario definire l'articolo che si sta creando, ad esempio un nuovo elenco di clienti o una richiesta di servizio. Se si sta definendo un metodo GET, non è necessario inviare il corpo di un metodo, pertanto non è necessario specificare un tipo di supporto.
1. Selezionare il tipo di supporto per il corpo del metodo, ovvero il formato del messaggio che si sta inviando, ad esempio testo, immagini o moduli Web.
  A seconda del tipo, ad esempio non immettere uno schema per un tipo di immagine, è possibile aggiungere uno schema, un esempio o entrambi.
  Quando si definisce uno schema, aggiungere solo i dati necessari per la risorsa. In altre parole, non aggiungere dati non necessari che rallentano solo la trasmissione e potrebbero aumentare il potenziale di eventuali errori.
2. (Facoltativo) Fare clic su Schema e immettere uno schema (in formato JSON) nel riquadro dell'editor. Uno schema è simile a un modello per il corpo. È l'elemento utilizzato per definire il contenuto del messaggio.
3. (Facoltativo) Fare clic su Esempio e immettere un esempio (in formato JSON) nel riquadro dell'editor, che viene utilizzato dall'implementazione mock come risposta mock per il metodo. L'utilizzo di tali dati può aiutare a verificare il funzionamento dei metodi. L'esempio mostra i valori mock per i dati inviati nel corpo del messaggio come definito nel metodo POST della risorsa audits:
```
body: 
  application/json: 
    example: | 
      { 
        "Title": "Leaking Water Heater",
        "Username": "joh1017",  
        "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-49f7-9bd2-88966c45668f?user=lynn1014", 
        "Notes": "my water heater is broken"
      }                               
```
Fare clic su Aggiungi tipo di supporto per aggiungere altri tipi di supporto. Se si decide di non utilizzare il metodo, fare clic su X nel banner per eliminarlo.

Definisci risposta per il metodo

A seconda della richiesta, potrebbe essere necessario o meno una risposta. Una risposta descrive il processo di restituzione dei risultati dal servizio. È possibile definire una risposta che verifica che i dati richiesti siano stati restituiti oppure che si desideri ricevere o meno la richiesta. La definizione di una risposta è simile alla definizione di una richiesta. La differenza principale consiste nel selezionare un codice di stato per indicare il risultato della connessione.

Fare clic su Risposta per definire una o più risposte.
Fare clic su Aggiungi risposta e selezionare il codice di stato che si desidera restituire.
Per impostazione predefinita viene fornito un codice di stato pari a 200, ma se diverso dal codice desiderato, selezionarne uno dall'elenco a discesa.
- 2 xx indica che una connessione è riuscita.
- 3 xx indica che si è verificato un reindirizzamento.
- 4 xx indica che si è verificato un errore utente.
- 5 xx indica che si è verificato un errore del server.
Per consentire a chiunque utilizzi l'API per capire il motivo di un potenziale errore nell'API che si sta configurando, utilizzare un codice di stato HTTP per restituire il codice che meglio corrisponde alla situazione di errore.
Fornire una descrizione degli indicatori di codice.
Fare clic su Aggiungi intestazione, selezionare un'intestazione o una query di risposta, fornire il nome dell'intestazione o della query e un nome visualizzato per l'intestazione e il tipo di valore valido per l'intestazione.
Fare clic su Aggiungi tipo di supporto e selezionare il formato della risposta. A seconda del tipo di supporto selezionato, è possibile aggiungere parametri, schemi o esempi esattamente come per il corpo della richiesta.
1. Per il tipo di supporto basato su testo, ad esempio application/json o text/xml, fare clic su Schema per immettere uno schema (in formato JSON) per il corpo.
  Come nel corpo della richiesta, aggiungere solo i dati pertinenti al corpo della risposta. Non includere più dati di quelli effettivamente necessari per l'operazione.
2. Fare clic su Esempio per aggiungere i dati mock (in formato JSON) per il corpo della risposta. Utilizzare i dati mock per verificare il funzionamento dei metodi prima di eseguire il test con i dati reali.
3. Per il tipo di supporto basato su form (ad esempio multipart/form-data), fare clic su Aggiungi parametro e selezionare Obbligatorio se il parametro è obbligatorio. Specificare un nome e selezionare un tipo di valore. Facoltativamente, è possibile assegnare un nome al parametro.
4. Per il tipo di supporto basato su immagine, ad esempio image/png, non è necessario effettuare alcuna operazione poiché non esistono schemi o attributi da fornire.

L'esempio riportato di seguito mostra che è stata creata una risposta per il metodo POST della risorsa audits con il codice di stato 201 che indica che la creazione di una nuova risorsa è riuscita. L'esempio mostra anche un formato di risposta restituito application/json, un'intestazione Location aggiunta e il corpo del messaggio contenente i dati mock:

responses: 
  201: 
    description: | 
      The request has been fulfilled and resulted in a new resource 
      being created. The newly created resource can be referenced  
      by the URI(s)returned in the entity of the response, with the 
      most specific URI for the resource given by a Location header
      field.  

    headers:
      Location:
        displayName: Location
        description: |
          Identifies the location of the newly created resource.

        type: string
        example: |
          /20934

        required: true

    body: 
      application/json: 
        example: | 
          {
            "id": 20934,
            "title": "Lynn's Leaking Water Heater",
            "contact": {
               "name": "Lynn Adams",                 
               "street": "45 O'Connor Street",
               "city": "Ottawa", 
               "postalcode": "a1a1a1",
               "username": "johnbeta"
              },
           "status": "New",
           "driveTime": 30,
           "priority": "high",
           "notes": "My notes",
           "createdon": "2014-01-20 23:15:03 EDT",
           "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d74331d77/objects/6cdaa3a8-097e-49f7--9bd2-88966c45668f?user=lynn1014"
          }

Quando si definisce la risposta, è possibile decidere di eseguire il test degli endpoint o fare clic su Endpoint nella barra di navigazione per tornare alla pagina Risorse principale. Da tale pagina è possibile passare a un'altra pagina in API Designer per creare una cartella radice, tipi di risorsa o caratteristiche oppure aggiungere la documentazione dell'interfaccia API.

Se si decide di non utilizzare il metodo, fare clic sulla X nel banner per eliminarlo.

Crea un'API connettore REST

Usare la procedura guidata API connettore REST per creare, configurare ed eseguire il test dell'interfaccia API connettore.

Per ottenere un'interfaccia API del connettore di lavoro di base, è possibile fornire un nome ridotto per l'interfaccia API del connettore e un URL al servizio esterno.

È possibile effettuare le operazioni riportate di seguito.

Definire le regole per formare richieste o risposte specifiche per i dati a cui si desidera accedere.
Configurare i criteri di sicurezza lato client per il servizio al quale si accede.
Eseguire il test della connessione e verificare i risultati delle chiamate effettuate alla connessione.

È necessario creare un'interfaccia API e un'implementazione personalizzate per consentire alle applicazioni di richiamare le interfacce API del connettore e generare automaticamente l'interfaccia API e l'implementazione. Se si desidera eseguire questa operazione manualmente, è necessario creare un'interfaccia API personalizzata con le risorse appropriate, quindi implementare il codice personalizzato.

Impostare un connettore di base

È possibile creare un connettore funzionante completando le prime due pagine della procedura guidata API connettore di REST.

Fare clic su e selezionare Sviluppo, quindi selezionare API dal menu laterale.
Fare clic su REST (se si tratta della prima API del connettore da creare) o su Nuovo connettore e, dall'elenco a discesa, selezionare REST.
Identificare la nuova API del connettore REST fornendo quanto riportato di seguito.
1. Nome visualizzato API: il nome visualizzato nella lista delle interfacce API connettore.
2. Nome API: il nome univoco dell'interfaccia API del connettore.
  
  Per impostazione predefinita, questo nome viene aggiunto all'URI di base relativo come nome risorsa per l'API del connettore. È possibile visualizzare l'URI di base sotto il campo Nome API.
  
  Altra versione di questa API connettore, nessun'altra API connettore può avere lo stesso nome di risorsa.
3. Descrizione breve: questa descrizione verrà visualizzata nella pagina Connettori quando viene selezionata questa interfaccia API.
Fare clic su Crea.
Nella pagina Generale della finestra di dialogo API connettore REST impostare i valori di timeout.
- Timeout lettura HTTP: il tempo massimo (in millisecondi) che può trascorrere in attesa della lettura dei dati. Se non si specifica un valore, viene applicato il valore predefinito di 20 secondi.
- Timeout connessione HTTP: il tempo, in millisecondi, impiegato per la connessione all'URL remoto. Un valore di 0mms indica che è consentito un timeout infinito.
  
  I valori di timeout HTTP devono essere inferiori ai criteri Network_HttpRequestTimeout, che hanno un valore predefinito di 40,000 ms.
  
  Nota:
  Se si dispone del ruolo di amministratore di Mobile Cloud oltre al ruolo di sviluppatore del servizio, è possibile aprire il file policies.properties per visualizzare il valore dei criteri di rete per l'ambiente corrente dalla vista Amministratore. In caso contrario, chiedere all'amministratore di Mobile Cloud i valori.
Fare clic su Descrittore e immettere le informazioni di connessione per il servizio.

Se si fornisce un URL per un descrittore Swagger, le risorse disponibili vengono identificate e visualizzate ed è possibile selezionare quelle desiderate.

Nota:
Sono supportate solo le porte di accesso a Internet standard 80 e 443. Impossibile stabilire la connessione a un servizio utilizzando una porta personalizzata.
Fare clic su Salva.
(Facoltativo) Fare clic su Test, selezionare le credenziali di autenticazione ed eseguire le chiamate di test al servizio.

La pagina consente di configurare ulteriormente il connettore nei modi riportati di seguito.

Se è stato fornito un descrittore nella pagina Descrittore, andare alla pagina Risorse e selezionare i metodi per le risorse esposte.
Definire le regole.
Impostare i criteri di sicurezza.

Per essere sicuri della validità della configurazione dell'interfaccia API del connettore, è necessario eseguirne il test completo (non solo dalla pagina Test API connettore) prima di pubblicarla. In altre parole, è necessario eseguire il test anche dell'interfaccia API personalizzata (con la relativa implementazione) che utilizza questa interfaccia API del connettore. Essenzialmente, se si è pronti a pubblicare l'API del connettore, è necessario essere pronti anche per pubblicare l'API personalizzata che lo chiama.

Imposta regole

È possibile impostare le regole per definire le interazioni tra l'applicazione mobile e un servizio. Le regole consentono di aggiungere i valori dei parametri predefiniti per tutte le chiamate alle risorse nel servizio, le chiamate a un percorso proxy specifico e le chiamate per determinati tipi di operazioni (verbi). Ciò facilita l'applicazione di una sintassi coerente della stringa URL, consente allo sviluppatore di codice personalizzato di dover inserire questi valori e di rendere possibile il tracciamento delle varie chiamate mediante l'analitica.

È possibile creare una o più regole. Ogni regola può avere uno o più parametri di tipo Query e Header.

Se non viene applicata alcuna regola, tutte le chiamate vengono passate attraverso il proxy al servizio esistente.

Se il connettore non è già aperto, fare clic su e selezionare Sviluppo, quindi selezionare API dal menu laterale.
Selezionare l'API connettore da modificare e fare clic su Apri.
Selezionare Ruoli.
Fare clic su Nuova regola.
Fare clic su Aggiungi parametro e selezionare un tipo di parametro Query o Intestazione, quindi immettere il nome della query o dell'intestazione e il relativo valore.

Nota:

Sebbene sia possibile definire regole per impostare determinate intestazioni per impostazione predefinita, le regole non vengono applicate se il client che ha chiamato il connettore direttamente mediante un codice personalizzato o indirettamente, ad esempio da un browser Web o da un'applicazione mobile, ha già impostato le stesse intestazioni.

In particolare, l'impostazione del formato del corpo della richiesta viene in genere eseguita nel codice personalizzato con l'intestazione Content-Type e non come regola di connettore REST. Allo stesso modo, l'impostazione del formato del corpo della risposta viene effettuata anche nel codice personalizzato con l'intestazione Accept e non come regola di connettore REST.

È possibile aggiungere tutti i parametri a una regola nel modo desiderato, ma è preferibile non sovraccaricare una regola con troppe operazioni. Un costrutto di regole più semplice risulta più semplice da risolvere.
Espandere Risorse e modificare l'URL remoto per fornire una risorsa alla quale applicare la regola. Il valore dell'URL di base è quello immesso nell'impostazione del passo delle informazioni di base e non può essere modificato.
Selezionare Non applicare alle risorse di livello inferiore se si desidera che le regole vengano applicate solo al livello di risorsa specificato nell'URL remoto.
(Facoltativo) Deselezionare i metodi HTTP che non si desidera applicare alle regole appena definite. Per impostazione predefinita, tutti i metodi sono selezionati.
(Facoltativo) Fare clic su Nuova regola per creare un'altra regola.

Nota:

Se si definisce una regola in conflitto con un'altra regola, la prima regola applicata ha la precedenza e la regola in conflitto viene ignorata.

Al termine, fare clic su Salva e quindi su Avanti ( > ) per andare al passo successivo della configurazione dell'interfaccia API del connettore.

La descrizione della regola appena definita viene visualizzata nel banner Regola immediatamente sopra la sezione Parametri predefiniti. Ad esempio, sono stati forniti i seguenti valori:

URL remoto = https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle
URI locale = myMapAPI
Regola con il seguente parametro: Query:key:A3FAEAJ903022
Metodi HTTP GET e PUT

La descrizione della regola è la seguente:

Per la disponibilità di GET a https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle in myMapAPI/directions, includere Query:key=A3FAEAJ903022.

Se non sono state create regole, viene letta la descrizione:

Per ALL METHODS su https://maps.googleapis.com/maps/api/directions disponibile in myMapAPI, non verrà applicato alcun parametro predefinito.

Ora si dispone di un URI di base mappato al servizio esistente. Con il nostro esempio:

mobile/connector/myMapAPI/directions/json?origin=los+angeles&destination=seattle è mappato a https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle

Configurare i criteri di sicurezza e sostituire le proprietà

Prima di finalizzare l'API connettore, è necessario considerare come gestire la propria sicurezza. È possibile utilizzare criteri di sicurezza o intestazioni di autorizzazione. La selezione di un criterio di sicurezza che descrive lo schema di autenticazione del servizio al quale si sta effettuando la connessione è l'approccio consigliato.

Ogni criterio di sicurezza dispone di proprietà, denominate sostituzioni, che è possibile configurare. Un motivo per sostituire una proprietà di configurazione dei criteri è limitare il numero di criteri che è necessario gestire: anziché creare più criteri con configurazioni leggermente diverse, è possibile utilizzare lo stesso criterio generico e sostituire valori specifici per soddisfare i requisiti.

Per selezionare un criterio di sicurezza e impostarne le sostituzioni:

Se il connettore non è già aperto, fare clic su e selezionare Sviluppo, quindi su API dal menu laterale.
Selezionare l'API connettore da modificare e fare clic su Apri.
Selezionare Sicurezza.
Selezionare il criterio di sicurezza dalla lista di criteri disponibili e fare clic sulla freccia destra per spostarlo nella lista Criteri selezionati.
Selezionare un solo criterio per l'interfaccia API del connettore. Sotto la lista viene visualizzata una descrizione del criterio selezionato.
Specificare le sostituzioni, se applicabile, al criterio selezionato se non si desidera utilizzare i valori predefiniti.
Per sostituire una proprietà, immettere o selezionare un valore diverso da quello predefinito.
Fare clic su Salva per salvare le modifiche apportate oppure su Salva e chiudi per salvare le modifiche e uscire dalla procedura guidata API connettore di REST.
Fare clic su Successivo ( > ) per andare al passo successivo.