Gestire le specifiche dell'API

Questa pagina si applica ad Apigee e Apigee hybrid.

Questo documento descrive come gestire le specifiche dell'API nell'hub API. Consulta anche Introduzione alle specifiche dell'API.

Aggiungere una specifica API a una versione

Puoi aggiungere una o più specifiche dell'API a una versione dell'API. Scegli una di queste opzioni:

Aggiungere una specifica quando crei una versione

Utilizzando solo l'interfaccia utente, puoi aggiungere una specifica API contemporaneamente alla creazione di una versione. Puoi fornire l'URL di una specifica a cui puoi accedere o caricare un file di specifica direttamente dal tuo sistema.

Console

Per aggiungere una specifica a una nuova versione:

  1. Per iniziare, segui i passaggi descritti in Creare una versione dell'API. Quando raggiungi la pagina Aggiungi una nuova versione, puoi facoltativamente aggiungere un file di specifica alla versione:
    1. Inserisci un nome visualizzato per il file delle specifiche. Puoi utilizzare il nome che preferisci.
    2. Seleziona il tipo di file della specifica. Il tipo di specifica è un attributo del sistema configurabile. Vedi anche Attributi di sistema.
    3. Fornisci un URI che rimandi a un file di specifiche API valido a cui hai accesso oppure vai a un file di specifiche API sul tuo sistema.
    4. (Facoltativo) Se vuoi applicare una convalida rigorosa alla specifica caricata, seleziona la casella di controllo Limita il caricamento del file di specifica contenente errori. Quando questa opzione è selezionata, una specifica contenente errori di convalida non verrà caricata. Per impostazione predefinita, le specifiche contenenti errori vengono caricate.
  2. Completa la pagina Aggiungi una nuova versione e fai clic su Crea al termine.

Aggiungere una specifica a una versione esistente

Puoi utilizzare l'API REST o l'interfaccia utente per aggiungere una specifica API a una versione esistente.

Console

Per aggiungere una specifica direttamente a una versione:

  1. Nella console Google Cloud, vai alla pagina Hub API.

    Vai ad API Hub
  2. Fai clic su API.
  3. Individua l'API con la versione che vuoi modificare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco di API. Se necessario, utilizza la ricerca per trovare un'API.
  4. Seleziona un'API.
  5. Fai clic su Aggiungi file di specifica.
  6. Inserisci un nome visualizzato per il file delle specifiche. Puoi utilizzare il nome che preferisci.
  7. Seleziona il tipo di file della specifica. Il tipo di specifica è un attributo del sistema configurabile. Vedi anche Attributi di sistema.
  8. Fornisci un URI che rimandi a un file di specifiche API valido a cui hai accesso oppure vai a un file di specifiche API sul tuo sistema.
  9. (Facoltativo) Se vuoi applicare una convalida rigorosa alla specifica caricata, seleziona la casella di controllo Limita il caricamento del file di specifica contenente errori. Quando questa opzione è selezionata, una specifica contenente errori di convalida non verrà caricata. Per impostazione predefinita, le specifiche contenenti errori vengono caricate.
  10. Seleziona la versione a cui aggiungere il file di specifica.
  11. Fai clic su Crea.

REST

Per aggiungere una specifica API a una versione, utilizza l'API Aggiungi specifica API:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID/specs?spec_id=SPEC_ID' \
  -d "DATA_FILE or URI"

Sostituisci quanto segue:

  • API_PROJECT: il nome del progetto host di API Hub. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • API_LOCATION: la posizione del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco di una risorsa API.
  • VERSION_ID: l'ID di una versione associata alla risorsa API.
  • SPEC_ID: (Facoltativo) L'identificatore della specifica. Se non viene fornito, verrà utilizzato un ID generato dal sistema. Il nome deve essere una stringa di 4-63 caratteri, dove i caratteri validi sono /[a-z][0-9]-/.
  • DATA_FILE or URI: un file con codifica Base64 contenente una specifica API valida o un link a una specifica. Consulta l'esempio REST.

Esempio REST

In questo esempio, crea una nuova specifica in API Hub con una specifica OpenAPI codificata in base 64. Al caricamento, API Hub analizza la specifica e crea una nuova entità spec che include metadati descrittivi, nonché insiemi di entità di operazioni e definizioni. 

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d "@data.json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs?spec_id=dstreetcarts-spec

Esempio di output:

{
    "name": "projects/common-dev-1/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
    "displayName": "Test Spec 1",
    "specType": {},
    "contents": {
      "contents": [Base64-encoded contents of an OpenAPI 3.0.2 file] },
    "details": {
      "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
      "openApiSpecDetails": {
        "format": "OPEN_API_SPEC_3_0",
        "version": "1.0.11"
      }
    },
    "createTime": "2024-04-04T22:39:05.674986Z",
    "updateTime": "2024-04-04T22:39:05.674986Z"
  }

Per restituire i dettagli delle specifiche:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1

Output:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

Elenco delle specifiche

Questa sezione spiega come elencare le specifiche associate a una versione dell'API.

Console

Per elencare le specifiche con l'interfaccia utente:

  1. Nella console Google Cloud, vai alla pagina Hub API.

    Vai all'hub API
  2. Fai clic su API.
  3. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco di API. Se necessario, utilizza la ricerca per trovare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione che vuoi ispezionare.
  6. Seleziona una versione.
  7. Eventuali specifiche collegate alla versione sono elencate nella sezione File di specifica.

REST

Per elencare le specifiche associate a una versione dell'API, utilizza l'API List specifications:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs"
      -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Sostituisci quanto segue:

  • HUB_PROJECT: il nome del progetto host di API Hub. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • HUB_LOCATION: la posizione del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.

Ottenere i dettagli delle specifiche

Questa sezione spiega come ottenere i dettagli di una specifica API associata a una versione.

Console

Per visualizzare i dettagli di una specifica utilizzando l'interfaccia utente:

  1. Nella console Google Cloud, vai alla pagina Hub API.

    Vai ad API Hub
  2. Fai clic su API.
  3. Individua l'API con la versione contenente la specifica che vuoi esaminare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco di API. Se necessario, utilizza la ricerca per trovare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione che vuoi ispezionare.
  6. Seleziona una versione.
  7. Nella sezione File di specifiche, seleziona una specifica per visualizzarne i dettagli.

REST

Per visualizzare i dettagli di una specifica, utilizza l'API Get specification details:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Sostituisci quanto segue:

  • HUB_PROJECT: il nome del progetto host di API Hub. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • HUB_LOCATION: la posizione del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.
  • SPEC_ID: l'ID univoco della specifica.

Esempio di output:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
  "displayName": "Test Spec 1",
  "details": {
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
    "openApiSpecDetails": {
      "format": "OPEN_API_SPEC_3_0",
      "version": "1.0.11"
    }
  },
  "createTime": "2024-04-04T22:39:05.098508600Z",
  "updateTime": "2024-04-04T22:39:06.661264958Z"
}

Eliminare una specifica dell'API

Questa sezione spiega come eliminare una specifica API da una versione. L'eliminazione di una specifica comporta anche l'eliminazione delle operazioni associate dalla versione.

Console

Per eliminare le risorse API con l'interfaccia utente:

  1. Nella console Google Cloud, vai alla pagina Hub API.

    Vai ad API Hub
  2. Fai clic su API.
  3. Individua l'API con la versione che contiene la specifica che vuoi eliminare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco di API. Se necessario, utilizza la ricerca per trovare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione contenente la specifica che vuoi eliminare.
  6. Seleziona la versione.
  7. Nella sezione File di specifica, seleziona Elimina dal menu Azioni nella riga della specifica che vuoi eliminare.
  8. Fai clic su Elimina.

REST

Per eliminare una risorsa API dall'hub API, utilizza l'API Elimina risorsa API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X DELETE -H "Content-Type: application/json"

Sostituisci quanto segue:

  • HUB_PROJECT: il nome del progetto host di API Hub. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • HUB_LOCATION: la posizione del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.
  • SPEC_ID: l'ID univoco della specifica da eliminare.

Modificare i metadati della specifica

Puoi modificare alcuni dei metadati associati a una specifica archiviata in API Hub. Per un elenco dei metadati che puoi modificare, consulta l'API Spec Patch.

Console

Puoi apportare modifiche a una specifica esistente tramite la console Google Cloud. Ad esempio, puoi modificare il nome visualizzato, caricare un nuovo file di specifiche, modificare il tipo di file e modificare gli attributi:

  1. Nella console Google Cloud, vai alla pagina Hub API.

    Vai ad API Hub
  2. Fai clic su API.
  3. Individua l'API con la versione contenente la specifica che vuoi modificare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco di API. Se necessario, utilizza la ricerca per trovare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione contenente la specifica che vuoi modificare.
  6. Seleziona la versione.
  7. Nella pagina Versioni, individua la specifica che vuoi modificare.
  8. Seleziona Modifica dal menu Azioni nella riga della specifica che vuoi modificare.
  9. Nel riquadro di modifica della specifica, puoi modificare uno qualsiasi dei seguenti metadati della specifica:
    • Nome visualizzato
    • Tipo di file di specifica
    • Documento delle specifiche: vai a un nuovo file di specifiche da caricare.
    • (Facoltativo) Se vuoi applicare una convalida rigorosa alla specifica caricata, seleziona la casella di controllo Limita il caricamento del file di specifica contenente errori. Quando questa opzione è selezionata, non verrà caricata una specifica che contiene errori di convalida. Per impostazione predefinita, le specifiche contenenti errori vengono caricate.
    • Attributi definiti dall'utente (se presenti)
  10. Fai clic su Salva.

REST

Per modificare una specifica con l'API REST:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json"
    '{
      "display-name": DISPLAY_NAME.  # Use the request body to specify attribute changes
      "contents": {
         "contents": Base64-encoded string
         "mimeType": MIME_TYPE
      }
    }'

Sostituisci quanto segue:

  • HUB_PROJECT: il nome del progetto host di API Hub. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • HUB_LOCATION: la posizione del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.
  • SPEC_ID: l'ID univoco della specifica.
  • Corpo della richiesta: utilizza il corpo della richiesta per specificare gli attributi da modificare. Consulta Definizione della risorsa della specifica.

Visualizzare i risultati dell'analisi di lint delle specifiche

L'hub API fornisce un lint (strumento di convalida) integrato (Spectral) che convalida la specifica Open API della tua API. Consulta la sezione Convalidare le specifiche dell'API.

  1. Nella console Google Cloud, vai alla pagina Hub API.

    Vai all'hub API
  2. Fai clic su API.
  3. Individua l'API con la versione contenente le specifiche che vuoi esaminare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco di API. Se necessario, utilizza la ricerca per trovare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione contenente la specifica che vuoi esaminare.
  6. Fai clic su Visualizza risultati nella colonna Risultati lint per visualizzare i risultati del lint.

Recuperare i contenuti della specifica

Questa funzionalità ti consente di esaminare i contenuti di una specifica caricata nell'hub API.

Console

Per visualizzare i dettagli di una specifica utilizzando l'interfaccia utente:

  1. Nella console Google Cloud, vai alla pagina Hub API.

    Vai ad API Hub
  2. Fai clic su API.
  3. Individua l'API con la versione che contiene la specifica che vuoi eliminare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco di API. Se necessario, utilizza la ricerca per trovare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione contenente la specifica che vuoi esaminare.
  6. Fai clic sul nome della specifica per visualizzarne i contenuti.

REST

L'API recupera i contenuti non elaborati codificati in Base64 di una specifica API caricata nell'hub API. Utilizza l'API Get specification contents:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID:contents"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Sostituisci quanto segue:

  • HUB_PROJECT: il nome del progetto host di API Hub. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • HUB_LOCATION: la posizione del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.
  • SPEC_ID: l'ID univoco della specifica.

Esempio di output:

{
  "contents": "Base64-encoded file contents"
}