Implementa un'API personalizzata per un servizio REST di facciata

Quando si sviluppa un'applicazione mobile, in genere si inizia prima con il livello dell'interfaccia utente, quindi si connette l'applicazione a un'altra applicazione utilizzando i servizi Web REST. Questo approccio funziona bene per applicazioni piccole o semplici. Quando le applicazioni sono più grandi e si desidera connettersi con più servizi backend, è possibile introdurre inavvertitamente problemi di prestazioni e sicurezza.

È consigliabile iniziare a creare un layer API di facciata tra i servizi backend esterni e l'interfaccia utente per ridurre il numero di chiamate ai servizi backend quando possibile. Ad esempio, l'applicazione mobile può eseguire una singola chiamata al livello API della facciata che gestisce le chiamate ad altri servizi REST e consolida tutti i dati in entrata in un'unica risposta all'applicazione mobile.

Crea un'API personalizzata completa

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

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

Definisci endpoint

Puoi creare risorse per definire gli endpoint della tua API. Una risorsa è il punto cruciale di un'API. Ha un tipo, alcuni dati associati, una relazione con altre risorse e contiene uno o più metodi che agiscono su di esso. Una risorsa può essere praticamente qualsiasi cosa: un'immagine, un file di testo, una raccolta di altre risorse, una transazione logica, una procedura, ecc.

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, si crea 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, viene visualizzata un'icona sotto il collegamento Metodi. 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, che è un nome per la risorsa che semplifica l'identificazione nella documentazione dell'API.
Le risorse vengono elencate in base ai 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.

È possibile eliminare il disordine per individuare una risorsa più rapidamente passando alla modalità Compatta (è a destra di Nuova risorsa). La visualizzazione compatta nasconde la descrizione della risorsa, il tipo di risorsa e il percorso.

Aggiungi metodi alle risorse

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

Aggiungere alcuni metodi alla risorsa facendo clic su Metodi.

Se la risorsa per la quale si stanno definendo i metodi ha parametri di percorso, vengono visualizzati sopra Aggiungi metodo.
1. (Facoltativo) Fare clic su Obbligatorio se si desidera che i parametri del percorso vengano passati con ciascun metodo.
  Viene visualizzato il nome del parametro.
2. Fornire un nome visualizzato per il parametro e il codice di esempio.
3. Dall'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 viene più elencato nell'elenco dei metodi perché si utilizza un metodo una sola volta per risorsa (ad esempio, non è possibile definire due metodi DELETE per una singola risorsa). Un'icona per ogni metodo definito viene visualizzata nella parte superiore della pagina. Fare clic sull'icona di un metodo per passare direttamente alla relativa definizione.
(Facoltativo) Immettere nel campo Descrizione una breve descrizione del metodo.
(Facoltativo) Immettere un nome di visualizzazione per il metodo.
(Facoltativo) Fornire le caratteristiche da applicare al metodo.

Se non sono state definite caratteristiche risorsa, fare clic su Endpoint per tornare alla pagina Risorse principale e fare clic sul collegamento Tratte per definirne una. I tratti consentono 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 del servizio a cui si desidera connettersi. Ad esempio, se è stato selezionato un metodo POST, ora è possibile definire cosa creare. A tale scopo, aggiungere i 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 è necessario per il metodo.
1. Dare al parametro un nome e un nome visualizzato.
2. Selezionare un tipo di valore valido: Stringa, Numero, Numero intero, Data o Boolean.
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 accetta 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 multipli 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 che si stanno inviando al server. Ad esempio, se si sta definendo un metodo POST, sarà necessario definire l'elemento 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 un corpo del metodo in modo da non dover 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 form Web.
  A seconda del tipo (ad esempio, non si immette 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 allo scopo della risorsa. Cioè, non aggiungere dati inutili che rallenteranno solo la trasmissione e potenzialmente aumenteranno il potenziale di errori.
2. (Facoltativo) Fare clic su Schema e immettere uno schema (in formato JSON) nel riquadro dell'editor. Uno schema è come 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, utilizzato dall'implementazione mock come risposta mock per il metodo. L'utilizzo di dati mock può aiutarti a verificare il comportamento dei tuoi 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 Add Media Type per aggiungere altri tipi di supporto. Se si decide di non utilizzare il metodo, fare clic su X nel banner per eliminarlo.

Definire una risposta per il metodo

A seconda della richiesta, potrebbe essere necessaria o meno una risposta. Una risposta descrive il processo di restituzione dei risultati dal servizio. È possibile definire una risposta che verifichi che i dati richiesti siano stati restituiti o che si desideri una risposta che riconosca se la richiesta è stata ricevuta o meno. La definizione di una risposta è simile alla definizione di una richiesta. La differenza principale è che dovrai selezionare un codice di stato per farti sapere 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 da restituire.
Per impostazione predefinita viene fornito un codice di stato pari a 200, ma se non si tratta del codice desiderato, selezionarne uno dall'elenco a discesa.
- 2xx indica che la connessione è riuscita.
- 3xx indica che si è verificato un reindirizzamento.
- 4xx indica che si è verificato un errore dell'utente.
- 5xx indica che si è verificato un errore del server.
Per aiutare chiunque utilizzi l'API a comprendere il motivo di un potenziale errore nell'API che si sta configurando, utilizzare un codice di stato HTTP per restituire il codice che corrisponde meglio alla situazione di errore.
Fornire una descrizione degli elementi designati dal codice.
Fare clic su Aggiungi intestazione, selezionare una risposta Intestazione o Query, specificare 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 proprio come si è fatto 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 per il corpo della richiesta, aggiungere solo dati pertinenti al corpo della risposta. Non includere più dati di quelli effettivamente necessari per l'operazione.
2. Fare clic su Esempio per aggiungere dati mock (in formato JSON) per il corpo della risposta. Utilizza i dati mock per verificare il comportamento dei tuoi metodi prima di eseguire test con 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. Quindi fornire un nome e selezionare un tipo di valore. Facoltativamente, è possibile assegnare un nome al parametro.
4. Per il tipo di supporto basato su immagini (ad esempio, image/png), non è necessario eseguire alcuna operazione perché non sono presenti schemi o attributi da fornire.

L'esempio seguente mostra che è stata creata una risposta per il metodo POST della risorsa audits con un codice di stato 201 che indica che la creazione di una nuova risorsa è riuscita. L'esempio mostra anche un formato di risposta di restituzione di 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 oppure fare clic su Endpoint nella barra di navigazione per tornare alla pagina Risorse principale. Da qui è possibile passare a un'altra pagina in API Designer per creare una radice, tipi di risorse o caratteristiche oppure aggiungere documentazione API.

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

Creare un'API connettore REST

Utilizzare la procedura guidata API connettore REST per creare, configurare e sottoporre a test l'API connettore.

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

Da lì è possibile:

Definire le regole per formulare richieste o risposte specifiche per i dati a cui si desidera accedere.
Configurare i criteri di sicurezza lato client per il servizio a cui si sta accedendo.
Eseguire il test della connessione ed eseguire il test dei risultati delle chiamate effettuate alla connessione.

È necessario creare un'API e un'implementazione personalizzate per consentire alle applicazioni di chiamare le API connettore e generare automaticamente l'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 del connettore REST.

Fare clic su e selezionare Sviluppo, quindi API dal menu laterale.
Fare clic su REST (se si tratta della prima API connettore da creare) o su Nuovo connettore e selezionare REST dall'elenco a discesa.
Identificare la nuova API connettore REST fornendo quanto riportato di seguito.
1. Nome visualizzato API: il nome visualizzato nella lista delle API connettore.
2. Nome API: il nome univoco dell'interfaccia API connettore.
  
  Per impostazione predefinita, questo nome viene aggiunto all'URI di base relativo come nome risorsa per l'API connettore. È possibile visualizzare l'URI di base sotto il campo Nome API.
  
  Oltre a una nuova versione di questa interfaccia API connettore, nessun'altra interfaccia API connettore può avere lo stesso nome risorsa.
3. Descrizione breve: questa descrizione verrà visualizzata nella pagina Connettori quando questa API è selezionata.
Fare clic su Crea.
Nella pagina Generale della finestra di dialogo API connettore REST, impostare i valori di timeout riportati di seguito.
- Timeout lettura HTTP: il tempo massimo (in millisecondi) che può essere impiegato per attendere la lettura dei dati. Se non si fornisce 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 0 mm indica che è consentito un timeout infinito.
  
  I valori di timeout HTTP devono essere inferiori al criterio Network_HttpRequestTimeout, il cui valore predefinito è 40.000 ms.
  
  Nota
  Se si dispone di un ruolo di amministratore cloud mobile 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 Mobile Cloud i valori.
Fare clic su Descriptor e immettere le informazioni di connessione per il servizio.

Se si fornisce un URL 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 effettuare chiamate di test al servizio.

È quindi possibile configurare ulteriormente il connettore nei modi riportati di seguito.

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

Per assicurarsi che la configurazione dell'API connettore sia valida, è necessario testarla in modo approfondito (non solo dalla pagina Test API connettore) prima di pubblicarla. Vale a dire, dovresti anche testare l'API personalizzata (con la sua implementazione) che utilizza questa API connettore. In sostanza, se sei pronto a pubblicare l'API connettore, dovresti anche essere pronto a pubblicare l'API personalizzata che la chiama.

Imposta regole

Le regole vengono impostate per definire le interazioni tra l'applicazione Mobile e un servizio. Le regole consentono di aggiungere valori di parametro predefiniti per tutte le chiamate alle risorse nel servizio, alle chiamate a un percorso proxy specifico e alle chiamate per determinati tipi di operazioni (verbi). Ciò consente di applicare una sintassi coerente della stringa URL, salva lo sviluppatore di codice personalizzato dalla necessità di inserire questi valori e consente di tenere traccia delle diverse chiamate tramite 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 tramite il proxy al servizio esistente.

Se il connettore non è già aperto, fare clic su e selezionare Sviluppo, quindi API dal menu laterale.
Selezionare l'interfaccia API connettore che si desidera 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 tramite codice personalizzato o indirettamente, ad esempio da un browser Web o 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, non come regola connettore REST. Analogamente, l'impostazione del formato del corpo della risposta viene eseguita anche nel codice personalizzato con l'intestazione Accept, non come regola connettore REST.

È possibile aggiungere a una regola il numero desiderato di parametri, ma è preferibile non sovraccaricare una regola con troppe operazioni. Un costrutto di regole più semplice è più facile da risolvere.
Espandere le risorse e modificare l'URL remoto per fornire una risorsa a cui applicare la regola. Il valore dell'URL di base è quello immesso nel passo di impostazione 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, la prima regola applicata ha la precedenza e la regola in conflitto viene ignorata.

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

La descrizione della regola appena definita viene visualizzata nel banner Regola appena sopra la sezione Parametri predefiniti. Si supponga, ad esempio, di aver fornito 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 GET a https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle disponibile all'indirizzo myMapAPI/directions, includere Query:key=A3FAEAJ903022.

Se non sono state create regole, la descrizione leggerà:

Per TUTTI I METODI a https://maps.googleapis.com/maps/api/directions disponibile ALL'indirizzo myMapAPI, non verranno applicati parametri predefiniti.

Ora si dispone di un URI di base mappato al servizio esistente. Usando 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 le proprietà di sostituzione

Prima di finalizzare l'API connettore, dovresti considerare come gestirne la sicurezza. È possibile utilizzare criteri di sicurezza o intestazioni di autorizzazione. La selezione di un criterio di sicurezza che descriva lo schema di autenticazione del servizio a cui ci si sta connettendo è l'approccio consigliato.

Ogni criterio di sicurezza include proprietà, denominate override, che è possibile configurare. Uno dei motivi per cui si sostituisce una proprietà di configurazione dei criteri consiste nel limitare il numero di criteri da 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 , selezionare Sviluppo e quindi API dal menu laterale.
Selezionare l'interfaccia API connettore che si desidera modificare e fare clic su Apri.
Selezionare Sicurezza.
Selezionare il criterio di sicurezza dalla lista dei criteri disponibili e fare clic sulla freccia destra per spostarlo nella lista Criteri selezionati.
Selezionare un solo criterio per l'API connettore. Sotto la lista viene visualizzata una descrizione di un criterio selezionato.
Se applicabile, specificare le sostituzioni al criterio selezionato se non si desidera utilizzare i valori predefiniti.
Per eseguire l'override di una proprietà, immettere o selezionare un valore diverso da quello predefinito.
Fare clic su Salva per salvare le modifiche oppure su Salva e chiudi per salvare le modifiche e uscire dalla procedura guidata API connettore REST.
Fare clic su Avanti (>) per andare al passo successivo.