Implementare un'interfaccia API personalizzata per un servizio REST con priorità massima

Quando si sviluppa un'applicazione mobile, di solito si inizia con il layer dell'interfaccia utente e successivamente si connette l'applicazione con un'altra applicazione mediante i servizi Web di REST. Questo approccio funziona bene per applicazioni di piccole dimensioni o semplici. Quando le applicazioni sono più grandi e si desidera connettersi con più servizi backend, è possibile introdurre involontariamente le prestazioni e i problemi di sicurezza.

Si consiglia di iniziare a creare un layer API faWORKFLOWSTATUSade 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 è in grado di eseguire una singola chiamata al layer API faWORKFLOWSTATUSade che gestisce le chiamate ad altri servizi REST e consolida tutti i dati in entrata in una singola risposta all'applicazione mobile.

Creare un'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 è la CRL di un'interfaccia API. Include un tipo, alcuni dati ad esso associati, una relazione con altre risorse e uno o più metodi che ne fanno parte. Una risorsa può essere quasi tutti: 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 andare 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, ovvero il nome della risorsa che facilita l'identificazione nella documentazione API.
Le risorse vengono elencate in base al relativo nome visualizzato 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 senza averne 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 andare direttamente alla definizione del metodo.

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

Aggiungere metodi alle risorse personali

I metodi sono azioni che è possibile eseguire su una risorsa. La pagina Metodi mostra un solo metodo alla volta. Dopo aver definito almeno due metodi, è possibile fare clic sull'icona relativa a 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 dispone di parametri di percorso, sopra Aggiungi metodo vengono visualizzati.
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. Nell'elenco a discesa selezionare il tipo di valore valido per il parametro.
Fare clic su Aggiungi metodo, quindi selezionare il metodo desiderato.

Dopo aver selezionato un metodo, esso 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 sull'icona di un metodo per andare direttamente alla relativa definizione.
(Facoltativo) Immettere una breve descrizione del metodo nel campo Descrizione.
(Facoltativo) Immettere un nome visualizzato per il metodo.
(Facoltativo) Fornire eventuali caratteristiche da applicare al metodo.

Se non è stata definita alcuna caratteristica di risorsa, fare clic su Endpoint per tornare alla pagina Risorse principale e fare clic sul collegamento Tratta per definirne una. Occorre definire una raccolta di operazioni simili.

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

Definire una richiesta per il metodo

Una volta selezionato un metodo, definire la richiesta che si sta effettuando il 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 al parametro e un nome visualizzato.
2. Selezionare un tipo di valore valido: Stringa, Numero, Numero intero, Data o Booleano.
3. (Facoltativo) Fornire la descrizione del parametro e un esempio che è possibile 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 assume un valore numerico, e un altro parametro, auditName, che assume un valore di 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, un metodo GET viene definito con i parametri della 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'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 un corpo del metodo in modo che non sia 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 form Web.
  A seconda del tipo (ad esempio, non immettere uno schema per un tipo di immagine), è possibile aggiungere uno schema o un esempio o entrambi.
  Quando si definisce uno schema, aggiungere solo i dati necessari allo scopo della risorsa. In altre parole, non aggiungere dati non necessari che saranno lenti solo per la trasmissione e potrebbero aumentare il potenziale numero di 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. Si tratta dell'elemento da utilizzare 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 dei dati mock consente di 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 voler utilizzare il metodo, fare clic sulla 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 che si desideri definire una risposta che verifica che i dati richiesti siano stati restituiti oppure che si desideri una risposta che conferma se la richiesta è stata ricevuta o meno. La definizione di una risposta è simile alla definizione di una richiesta. La differenza principale consiste nel selezionare un codice di stato per consentire all'utente di conoscere il risultato della connessione.

Fare clic su Risposta per definire una o più risposte.
Fare clic su Aggiungi risposta, quindi 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 la 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 di comprendere 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 proprio 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 al corpo della risposta solo i dati pertinenti. 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. 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 eseguire alcuna operazione poiché non sono presenti 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 la creazione di una nuova risorsa. L'esempio mostra anche il 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 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 risorsa o caratteristiche oppure aggiungere la documentazione dell'API.

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

Crea un'interfaccia API connettore REST

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

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

Da qui è possibile effettuare le operazioni riportate di seguito.

Definire 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 ed eseguire il test dei risultati delle chiamate effettuate alla connessione.

È necessario creare un'interfaccia API e un'implementazione personalizzate per consentire alle applicazioni di chiamare le interfacce API del connettore e generare l'interfaccia API e l'implementazione in modo automatico. 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 di lavoro completando le prime due pagine della procedura guidata API connettore REST.

Fare clic su e selezionare Sviluppo, quindi selezionare 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 interfaccia 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 della risorsa per l'interfaccia API connettore. L'URL di base è visibile sotto il campo Nome API.
  
  Diversamente da una nuova versione di questa interfaccia API connettore, nessun' altra interfaccia API connettore può avere lo stesso nome di 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:
- Timeout lettura HTTP: il tempo massimo, in millisecondi, che può essere impiegato in attesa di 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 0mms indica che è consentito un timeout infinito.
  
  I valori di timeout HTTP devono essere inferiori al criterio Network_HttpRequestTimeout, che ha 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 del descrittore Swagger, le risorse disponibili vengono identificate e visualizzate ed è possibile selezionare quelle desiderate.

Nota
Sono supportate solo le porte di accesso Internet standard 80 e 443. Impossibile effettuare 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.

Da qui è possibile 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 che la configurazione dell'API connettore sia valida, è necessario eseguirne il test (non solo dalla pagina Test API connettore) prima di pubblicarla. In altre parole, è necessario eseguire il test dell'interfaccia API personalizzata (con la relativa implementazione) che utilizza questa interfaccia API connettore. In pratica, se si è pronti a pubblicare l'API del connettore, è necessario essere pronti anche per pubblicare l'API personalizzata che la chiama.

Imposta regole

È possibile impostare le regole 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 del servizio, di chiamare un percorso proxy specifico e di richiamare determinati tipi di operazioni (verbi). Ciò consente di applicare una sintassi coerente della stringa URL, di salvare lo sviluppatore di codice personalizzato dalla necessità di inserire questi valori e di tenere traccia delle diverse 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 vengono applicate regole, 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'interfaccia API connettore che si desidera modificare, quindi fare clic su Apri.
Selezionare Ruoli.
Fare clic su Nuova regola.
Fare clic su Aggiungi parametro, 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 avviene di solito nel codice personalizzato con l'intestazione Content-Type e non come regola del connettore REST. Allo stesso modo, l'impostazione del formato del corpo della risposta viene eseguita anche nel codice personalizzato con l'intestazione Accept e non come regola del connettore REST.

È possibile aggiungere tutti i parametri a una regola che si desidera, ma è preferibile non sovraccaricare una regola con troppe operazioni. Un costrutto di regola più semplice è facile da risolvere i problemi.
Espandere Risorse e modificare l'URL remoto in modo da fornire una risorsa a cui applicare la regola. Il valore dell'URL di base corrisponde a 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 regola, la prima regola applicata ha la precedenza e la regola in conflitto viene ignorata.

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

La descrizione della regola appena definita viene visualizzata nel banner Regola solo sopra la sezione Parametri predefiniti. Si supponga, ad esempio, di fornire 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
GET e PUT, metodi HTTP

La descrizione della regola è la seguente:

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

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

Per ALL METHODS a https://maps.googleapis.com/maps/api/directions disponibile all'indirizzo myMapAPI, non verrà applicato alcun parametro predefinito.

Ora si dispone di un URI di base mappato al servizio esistente. Utilizzo dell'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'interfaccia API del connettore, è necessario considerare come gestirne la 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 ci si connette costituisce l'approccio consigliato.

Ogni criterio di sicurezza dispone di proprietà, definite sostituzioni, che è possibile configurare. Un motivo per sostituire una proprietà di configurazione dei criteri è limitare il numero di criteri che è necessario conservare: 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 impostare le sostituzioni dei criteri:

Se il connettore non è già aperto, fare clic su e selezionare Sviluppo, quindi su API dal menu laterale.
Selezionare l'interfaccia API connettore che si desidera modificare, quindi 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'interfaccia API connettore. Sotto la lista viene visualizzata una descrizione del criterio selezionato.
Specificare gli override, 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 il lavoro oppure su Salva e chiudi per salvare il lavoro e uscire dalla procedura guidata API connettore REST.
Fare clic su Successivo ( > ) per andare al passo successivo.