Pubblica le tue API

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Pubblica le API nel tuo portale per renderle disponibili per il consumo da parte degli sviluppatori di app, come descritto nelle sezioni seguenti.

Panoramica della pubblicazione dell'API

Il processo di pubblicazione delle API nel portale prevede due fasi:

1. Seleziona il prodotto API che vuoi pubblicare sul tuo portale.
2. Esegui il rendering della documentazione di riferimento dell'API da uno snapshot del tuo documento OpenAPI o dello schema GraphQL per consentire agli sviluppatori di app di conoscere le tue API. Per ulteriori informazioni sugli snapshot, consulta Che cos'è uno snapshot?.

Che cosa viene pubblicato sul portale?

SmartDocumenti (OpenAPI)

Quando pubblichi un'API utilizzando un documento OpenAPI, la documentazione di riferimento dell'API SmartDocs viene aggiunta al tuo portale.

Gli sviluppatori possono esaminare la documentazione di riferimento dell'API SmartDocs e utilizzare il riquadro Prova questa API per effettuare una richiesta API e visualizzare l'output. Prova questa API funziona con endpoint non protetti o protetti utilizzando l'autenticazione di base, con chiave API o OAuth, in base al metodo di sicurezza definito nel documento OpenAPI. Per OAuth sono supportati i seguenti flussi: codice di autorizzazione, password e credenziali client.

Fai clic su per espandere il riquadro Prova questa API. Il riquadro espanso consente di visualizzare le chiamate curl e gli esempi di codice in vari formati, come HTTP, Python, Node.js e altri, come mostrato di seguito.

Explorer GraphQL

Quando pubblichi un'API utilizzando uno schema GraphQL, GraphQL Explorer viene aggiunto al tuo portale. GraphQL Explorer è un'area giochi interattiva per eseguire query sull'API. Explorer si basa su GraphiQL, un'implementazione di riferimento dell'IDE GraphQL sviluppata da GraphQL Foundation.

Gli sviluppatori possono utilizzare GraphQL Explorer per esplorare la documentazione interattiva basata sugli schemi, creare ed eseguire query, visualizzare i risultati delle query e scaricare lo schema. Per proteggere l'accesso all'API, gli sviluppatori possono inserire le intestazioni di autorizzazione nel riquadro Intestazioni della richiesta.

Per ulteriori informazioni su GraphQL, consulta graphql.org.

Che cos'è uno snapshot?

Ogni documento OpenAPI o GraphQL funge da fonte attendibile per tutto il ciclo di vita di un'API. Lo stesso documento viene utilizzato in ogni fase del ciclo di vita delle API, dallo sviluppo alla pubblicazione e al monitoraggio. Quando modifichi un documento, devi essere consapevole dell'impatto che le modifiche hanno sulla tua API attraverso altre fasi del ciclo di vita, come descritto in Cosa succede se modifico un documento?

Quando pubblichi l'API, crei uno snapshot del documento OpenAPI o GraphQL per eseguire il rendering della relativa documentazione di riferimento. Questo snapshot rappresenta una versione specifica del documento. Se modifichi il documento, puoi decidere di acquisire un'altra istantanea del documento per riflettere le ultime modifiche nella documentazione di riferimento dell'API.

Informazioni sugli URL di callback

Se le tue app richiedono un URL di callback, ad esempio quando utilizzi il tipo di concessione del codice di autorizzazione OAuth 2.0 (spesso indicato come "OAuth a tre vie"), puoi richiedere agli sviluppatori di specificare un URL di callback quando registrano le loro app. L'URL di callback specifica in genere l'URL di un'app designata per ricevere un codice di autorizzazione per conto dell'app client. Per ulteriori informazioni, consulta Implementazione del tipo di concessione del codice di autorizzazione.

Puoi configurare se richiedere o meno un URL di callback durante la registrazione dell'app quando aggiungi un'API al portale. Puoi modificare questa impostazione in qualsiasi momento, come descritto in Gestire l'URL di callback per un'API.

Quando registrano un'app, gli sviluppatori devono inserire un URL di callback per tutte le API che lo richiedono, come descritto in Registrare app.

Configura il proxy API in modo che supporti "Prova questa API"

Prima di pubblicare le tue API utilizzando un documento OpenAPI, devi configurare il proxy API per supportare le richieste nel riquadro Prova questa API nella documentazione di riferimento dell'API SmartDocs, come segue:

• Aggiungi il supporto CORS ai proxy API per applicare le richieste multiorigine lato client

  CORS è un meccanismo standard che consente alle chiamate JavaScript XMLHttpRequest (XHR) eseguite in una pagina web di interagire con risorse da domini non di origine. CORS è una soluzione comunemente implementata per il "criterio della stessa origine" applicata da tutti i browser.

• Aggiorna la configurazione del proxy API se utilizzi l'autenticazione di base o OAuth2

La tabella seguente riassume i requisiti di configurazione del proxy API per il supporto del pannello Prova questa API nella documentazione di riferimento dell'API SmartDocs in base all'accesso per l'autenticazione.

Esplora il catalogo delle API

Per visualizzare il catalogo delle API: 1. Seleziona Pubblica > Portals e seleziona il tuo portale. 2. Fai clic su Catalogo API nella home page del portale. In alternativa, puoi selezionare Catalogo API nel menu a discesa del portale nella barra di navigazione in alto.

La scheda API nel catalogo API mostra un elenco delle API che sono state aggiunte al tuo portale.

Come evidenziato nella figura precedente, la scheda API ti consente di:

• Visualizza i dettagli delle API disponibili nel tuo portale
• Aggiungi un'API al portale
• Modifica un'API sul tuo portale eseguendo una o più delle seguenti attività:
  • Gestisci l'istantanea di un documento associato a un prodotto API per aggiornare la documentazione di riferimento dell'API
  • Pubblicare o annullare la pubblicazione di un'API sul portale
  • Gestisci la visibilità di un'API nel portale:
  • Gestire l'URL di callback per un'API
  • Gestire l'immagine per una scheda API
  • Codificare un'API utilizzando le categorie
  • Modificare il titolo e la descrizione dell'API
• Rimuovere un'API dal portale
• Gestisci le categorie utilizzate per scoprire le API correlate
• Identifica rapidamente le specifiche non aggiornate o che sono state eliminate dall'archivio specifiche
• Identifica rapidamente "orfani" API il cui prodotto API associato è stato rimosso da Edge e ricreano il prodotto API o elimina l'API dal portale

Aggiungi un'API al portale

Per aggiungere un'API al portale:

1. Accedi al catalogo delle API.
2. Fai clic sulla scheda API, se non è già selezionata.

3. Fai clic su +.

   Viene visualizzata la finestra di dialogo Aggiungi un prodotto API al catalogo.

4. Seleziona il prodotto API che vuoi aggiungere al tuo portale.

5. Fai clic su Avanti. Viene visualizzata la pagina dei dettagli dell'API.

6. Configura i contenuti della documentazione di riferimento dell'API e la relativa visibilità sul portale:

   Campo	Descrizione
   Pubblicato	Seleziona Published (Pubblicata) per pubblicare l'API sul tuo portale. Deseleziona la casella di controllo se non vuoi pubblicare l'API. Puoi modificare l'impostazione in un secondo momento, come descritto in Pubblicare o annullare la pubblicazione di un'API sul portale.
   Mostra titolo	Aggiorna il titolo dell'API che viene visualizzato nel catalogo. Per impostazione predefinita, viene utilizzato il nome del prodotto API. Puoi modificare il titolo visualizzato in un secondo momento, come descritto in Modificare il titolo e la descrizione visualizzati.
   Mostra descrizione	Aggiorna la descrizione dell'API che viene visualizzata nel catalogo. Per impostazione predefinita, viene utilizzata la descrizione del prodotto API. Puoi modificare la descrizione visualizzata in un secondo momento, come descritto in Modificare il titolo e la descrizione visualizzati.
   Richiedi agli sviluppatori di specificare un URL di callback	Attiva questa opzione se vuoi richiedere agli sviluppatori di app di specificare un URL di callback. Puoi aggiungere o aggiornare l'URL di callback in un secondo momento, come descritto in Gestire l'URL di callback per un'API.
   Documentazione relativa all'API	Per utilizzare un documento OpenAPI: . Seleziona Documento OpenAPI. Fai clic su Seleziona documento. Esegui uno dei seguenti passaggi: Fai clic sulla scheda Le mie specifiche e seleziona una specifica dall'archivio. Fai clic sulla scheda Upload File (Carica file) e carica un file. Fai clic sulla scheda Importa da un URL e importa una specifica da un URL. Fai clic su Seleziona. Per utilizzare uno schema GraphQL: Seleziona Schema GraphQL. Fai clic su Seleziona documento. Vai allo schema GraphQL e selezionalo. Fai clic su Seleziona. In alternativa, puoi selezionare Nessuna documentazione e aggiungerne una in un secondo momento dopo aver aggiunto l'API, come descritto in Gestione dello snapshot del documento.
   Visibilità API	Se non hai effettuato la registrazione alla versione beta della funzionalità di gestione dei segmenti di pubblico, seleziona una delle seguenti opzioni: Utenti anonimi per consentire a tutti gli utenti di visualizzare l'API. Utenti registrati per consentire solo agli utenti registrati di visualizzare l'API. Se hai effettuato la registrazione alla versione beta della funzionalità di gestione dei segmenti di pubblico, seleziona una delle seguenti opzioni: Pubblica (visibile a chiunque) per consentire a tutti gli utenti di visualizzare l'API. Utenti autenticati per consentire solo agli utenti registrati di visualizzare l'API. Segmenti di pubblico selezionati per selezionare i segmenti di pubblico specifici che vuoi che possano visualizzare l'API. Puoi gestire la visibilità del pubblico in un secondo momento, come descritto in Gestire la visibilità di un'API nel portale.
   Visualizza immagine	Per visualizzare un'immagine nella scheda API della pagina API, fai clic su Seleziona immagine. Nella finestra di dialogo Seleziona immagine, scegli un'immagine esistente, carica una nuova immagine o fornisci l'URL di un'immagine esterna e fai clic su Seleziona. Visualizza l'anteprima della miniatura dell'API e fai clic su Seleziona. Puoi aggiungere un'immagine in un secondo momento, come descritto in Gestire l'immagine di una scheda API. Quando specifichi un'immagine con un URL esterno, l'immagine non verrà caricata negli asset. inoltre, il caricamento dell'immagine nel portale integrato sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata dai criteri di sicurezza dei contenuti.
   Categorie	Aggiungi le categorie a cui l'API verrà codificata per consentire agli sviluppatori di app di scoprire le API correlate nella pagina delle API. Per identificare una categoria: Seleziona una categoria dall'elenco a discesa. Aggiungi una nuova categoria digitandone il nome e premendo Invio. La nuova categoria verrà aggiunta alla pagina Categorie e resa disponibile durante l'aggiunta o la modifica di altre API.

7. Fai clic su Salva.

Gestisci l'istantanea del documento

Dopo aver pubblicato l'API, puoi acquisire in qualsiasi momento un nuovo snapshot del documento OpenAPI o GraphQL per aggiornare la documentazione di riferimento dell'API pubblicata sul tuo portale.

Per gestire l'istantanea del documento:

1. Accedi al catalogo delle API.
2. Fai clic sulla scheda API, se non è già selezionata.
3. Fai clic nella riga dell'API che vuoi modificare.
4. Controlla lo stato dello snapshot. Se i dati non sono aggiornati, viene visualizzato il seguente messaggio:
5. Fai clic su .
6. Esegui una delle seguenti attività:
   • Per aggiornare lo snapshot di un documento OpenAPI non aggiornato, fai clic su Aggiorna snapshot.
   • Per modificare il documento utilizzato per generare la documentazione per l'API, nella sezione Documentazione API fai clic su Seleziona documento e seleziona il nuovo documento.
7. Fai clic su Salva.

La documentazione di riferimento dell'API viene visualizzata dal documento e aggiunta alla pagina di riferimento dell'API. Lo stato dello snapshot è aggiornato a oggi:

Pubblicare o annullare la pubblicazione di un'API sul portale

Per pubblicare o annullare la pubblicazione di un'API sul tuo portale:

1. Accedi al catalogo delle API.
2. Fai clic sulla scheda API, se non è già selezionata.
3. Fai clic nella riga dell'API che vuoi modificare.
4. Fai clic su .
5. In Dettagli API, seleziona o deseleziona Pubblicata (elencata nel catalogo) rispettivamente per pubblicare o annullare la pubblicazione dell'API sul tuo portale.
6. Fai clic su Salva.

Gestisci la visibilità di un'API sul tuo portale

Gestisci la visibilità di un'API nel tuo portale consentendo l'accesso a:

• Pubblico (visibile a tutti)
• Utenti autenticati
• Segmenti di pubblico selezionati (se hai effettuato la registrazione alla versione beta della funzionalità di gestione dei segmenti di pubblico)

Per gestire la visibilità di un'API nel tuo portale:

1. Accedi al catalogo delle API.
2. Fai clic sulla scheda API, se non è già selezionata.
3. Fai clic nella riga dell'API che vuoi modificare.
4. Fai clic su .
5. In Visibilità API, seleziona una delle seguenti opzioni:

6. Seleziona l'impostazione di visibilità. Se hai effettuato la registrazione alla versione beta della funzionalità segmenti di pubblico, seleziona una delle seguenti opzioni:

   • Pubblica (visibile a tutti) per consentire a tutti gli utenti di visualizzare la pagina.
   • Utenti autenticati per consentire solo agli utenti registrati di visualizzare la pagina.
   • Segmenti di pubblico selezionati per scegliere quelli specifici che potranno essere visualizzati nella pagina. Consulta Gestire i segmenti di pubblico per il portale.
   di Gemini Advanced. Altrimenti, seleziona una delle seguenti opzioni:
   • Utenti anonimi per consentire a tutti gli utenti di visualizzare la pagina.
   • Utenti registrati per consentire solo agli utenti registrati di visualizzare la pagina.

7. Fai clic su Invia.

Gestire l'URL di callback per un'API

Gestisci l'URL di callback per un'API. Consulta Informazioni sugli URL di callback.

Per gestire l'URL di callback per un'API:

1. Accedi al catalogo delle API.
2. Fai clic sulla scheda API, se non è già selezionata.
3. Fai clic nella riga dell'API che vuoi modificare.
4. Fai clic su .
5. In Dettagli API, seleziona o deseleziona Pubblicata (elencata nel catalogo) rispettivamente per pubblicare o annullare la pubblicazione dell'API sul tuo portale.
6. Fai clic su Salva.

Gestisci l'immagine per una scheda API

Gestisci l'immagine che viene visualizzata con una scheda API nella pagina delle API aggiungendo o modificando l'immagine corrente.

Per gestire l'immagine per una scheda API:

1. Accedi al catalogo delle API.
2. Fai clic sulla scheda API, se non è già selezionata.
3. Fai clic nella riga dell'API che vuoi modificare.
4. Fai clic su .

5. In Dettagli API:

   • Fai clic su Seleziona immagine per specificare o caricare un'immagine se al momento non è selezionata alcuna immagine.
   • Fai clic su Cambia immagine per specificare o caricare un'immagine diversa.
   • Fai clic sulla x nell'immagine per rimuoverla.

   Quando specifichi un'immagine, specifica un'immagine con un URL esterno utilizzato per l'articolo del catalogo oppure un percorso file immagine archiviati nel portale, ad esempio /files/book-tree.jpg. Quando specifichi l'URL di un'immagine esterna, l'immagine non essere caricati nelle tue risorse. Inoltre, il caricamento dell'immagine nella portale sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata da norme sulla sicurezza del contenuto.

6. Fai clic su Salva.

Taggare un'API utilizzando le categorie

Applica il tagging a un'API utilizzando le categorie in uno dei seguenti modi:

• Gestisci le categorie a cui vengono assegnati i tag di un'API durante la modifica dell'API, come descritto di seguito.
• Gestisci le API con tag a una categoria quando modifichi la categoria.

Per taggare un'API in categorie durante la modifica dell'API:

1. Accedi al catalogo delle API.
2. Fai clic sulla scheda API, se non è già selezionata.
3. Fai clic nella riga dell'API che vuoi modificare.
4. Fai clic su .
5. Fai clic nel campo Categorie ed esegui uno dei seguenti passaggi:
   .
   • Seleziona una categoria dall'elenco a discesa.
   • Aggiungi una nuova categoria digitandone il nome e premendo Invio. La nuova categoria verrà aggiunta alla pagina Categorie e resa disponibile durante l'aggiunta o la modifica di altre API.
6. Ripeti la procedura per assegnare all'API più categorie.
7. Fai clic su Salva.

Modifica il titolo e la descrizione visualizzati

Per modificare il titolo e la descrizione visualizzati:

1. Accedi al catalogo delle API.
2. Fai clic sulla scheda API, se non è già selezionata.
3. Fai clic nella riga dell'API che vuoi modificare.
4. Fai clic su .
5. Modifica i campi Titolo visualizzato e Descrizione visualizzata come richiesto.
6. Fai clic su Salva.

Rimuovi un'API dal portale

Per rimuovere un'API dal portale:

1. Accedi al catalogo delle API.
2. Seleziona le API, se non sono già selezionate.
3. Posiziona il cursore sull'API nell'elenco per visualizzare il menu delle azioni.
4. Fai clic su .

Gestisci le categorie utilizzate per scoprire le API correlate

Codifica un'API utilizzando le categorie per consentire agli sviluppatori di app di scoprire le API correlate nella pagina API del portale online. Aggiungi e gestisci le categorie, come descritto nelle sezioni seguenti.

Esplorare la pagina Categorie

Per visualizzare la pagina Categorie:

1. Seleziona Pubblica > Portals e seleziona il tuo portale.
2. Fai clic su Catalogo API nella home page del portale.

   In alternativa, puoi selezionare Catalogo API nel menu a discesa del portale nella barra di navigazione in alto.

3. Fai clic sulla scheda Categorie.

La scheda Categorie nel catalogo delle API mostra l'elenco delle categorie definite per il portale.

Come evidenziato nella figura precedente, la pagina delle API consente di:

• Visualizzare le categorie e le API a cui sono taggati
• Aggiungi una categoria
• Modificare una categoria
• Eliminare una categoria
• Gestisci le API pubblicate nel tuo portale. Consulta la pagina Esplorare il catalogo delle API.

Aggiunta di una categoria

Aggiungi una categoria in uno dei seguenti modi:

• Inserisci il nome di una categoria quando aggiungi un'API al portale
• Aggiungi manualmente una categoria come descritto di seguito

La nuova categoria verrà aggiunta alla pagina Categorie e resa disponibile durante l'aggiunta o la modifica di altre API.

Per aggiungere manualmente una categoria:

1. Accedi alla pagina Categorie.
2. Fai clic su +.
3. Inserisci il nome della nuova categoria.
4. Facoltativamente, seleziona una o più API per il tagging della categoria.
5. Fai clic su Crea.

Modificare una categoria

Per modificare una categoria:

1. Accedi alla pagina Categorie.
2. Fai clic su .
3. Modifica il nome della categoria.
4. Aggiungi o rimuovi i tag API.
5. Fai clic su Salva.

Eliminare una categoria

Quando elimini una categoria, vengono eliminati anche tutti i relativi tag API.

Per eliminare una categoria:

1. Accedi alla pagina Categorie.
2. Posiziona il cursore sulla categoria che vuoi modificare per visualizzare il menu delle azioni.
3. Fai clic su .
4. Modifica il nome della categoria.
5. Aggiungere o rimuovere API.
6. Fai clic su Salva.

Risolvi i problemi relativi alle API pubblicate

Le sezioni seguenti forniscono informazioni per aiutarti a risolvere errori specifici relativi alle nostre API pubblicate.

Errore: impossibile recuperare l'errore restituito quando si utilizza Prova questa API

Quando utilizzi Prova questa API, se viene restituito l'errore TypeError: Failed to fetch, prendi in considerazione le seguenti possibili cause e soluzioni:

• Per gli errori di contenuti misti, l'errore potrebbe essere causato da un problema noto di swagger-ui. Una possibile soluzione è assicurarti di specificare HTTPS prima di HTTP nella definizione di schemes nel documento OpenAPI. Ad esempio:

  schemes:
     - https
     - http
  

• In caso di errori relativi alle restrizioni della condivisione delle risorse tra origini (CORS), assicurati che CORS sia supportato per i proxy API. CORS è un meccanismo standard che abilita le richieste multiorigine lato client. Vedi Configura il proxy API per supportare Prova questa API.

Errore: "Access-Control-Allow-Origin" L'intestazione contiene più valori "*, *", ma è consentito un solo valore

Quando utilizzi Prova questa API, potresti visualizzare il seguente messaggio di errore se l'intestazione Access-Control-Allow-Origin esiste già:

The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.

Per correggere questo errore, modifica il criterioAssignMessage in modo che utilizzi <Set> per impostare le intestazioni CORS anziché <Add>, come mostrato nell'estratto di seguito. Per ulteriori informazioni, leggi l'articolo della community pertinente.

<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Errore: campo intestazione della richiesta non consentito

Quando utilizzi Prova questa API, se ricevi un errore Request header field not allowed, simile all'esempio riportato di seguito, potresti dover aggiornare le intestazioni supportate dal criterio CORS. Ad esempio:

Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response

In questo esempio, devi aggiungere l'intestazione content-type alla sezione Access-Control-Allow-Headers del criterio CORSAssignMessage, come descritto in Collegamento di un criterio Aggiungi CORS a un nuovo proxy API.

Errore: accesso negato durante la chiamata a un proxy API utilizzando OAuth2

Il criterio OAuthV2 di Apigee restituisce una risposta di token che contiene determinate proprietà non conformi alla RFC. Ad esempio, il criterio restituirà un token con valore BearerToken, anziché il valore previsto conforme a RFC Bearer. Questa risposta token_type non valida può causare un errore Access denied quando utilizzi Prova questa API.

Per risolvere il problema, puoi creare un criterio JavaScript oAssignMessage per trasformare l'output del criterio in un formato conforme. Per ulteriori informazioni, vedi comportamenti non compatibili con RFC.