Gestisci specifiche 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.

Aggiungi una specifica API a una versione

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

Aggiungi una specifica quando crei una versione

Utilizzando solo la UI, puoi aggiungere una specifica API nel momento in cui crei una versione. Tu puoi fornire l'URL a una specifica a cui puoi accedere oppure caricare un file delle specifiche direttamente dal 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, in via facoltativa, puoi 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 o passa a un file con le specifiche delle API sul tuo sistema.
    4. (Facoltativo) Se vuoi applicare una convalida rigorosa alla specifica caricata, seleziona l'icona Casella di controllo Limita il caricamento del file di specifiche 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 dell'hub API.

    Vai all'hub API
  2. Fai clic su API.
  3. Individua l'API con la versione da modificare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco di API. Se necessario, utilizza la ricerca per individuare un'API.
  4. Seleziona un'API.
  5. Fai clic su Aggiungi file delle specifiche.
  6. Inserisci un nome visualizzato per il file delle specifiche. Puoi utilizzare il nome che preferisci.
  7. Seleziona il tipo di file delle specifiche. Il tipo di specifica è un 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, le specifiche che contengono errori di convalida non saranno caricate. Per impostazione predefinita, le specifiche contenenti errori vengono caricate.
  10. Seleziona la versione a cui aggiungere il file delle specifiche.
  11. Fai clic su Crea.

REST

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

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 dell'hub API. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • API_LOCATION: la località del progetto host. La località è stata scelta quando l'API è stato eseguito il provisioning dell'hub.
  • API_ID: l'ID univoco di una risorsa API.
  • VERSION_ID: l'ID di una versione collegata 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 nell'hub API con una codifica Base64 Specifica OpenAPI. Al momento del caricamento, l'hub API analizza la specifica e crea una nuova entità della specifica che include metadati descrittivi e insiemi di entità operative e di definizione. 

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 dell'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 da controllare.
  6. Seleziona una versione.
  7. Tutte le specifiche collegate alla versione sono elencate nella sezione File delle specifiche.

REST

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

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 dell'hub API. Il progetto host è stato selezionato quando è stato eseguito il provisioning dell'hub API.
  • HUB_LOCATION: la posizione del progetto host. La località è stata scelta quando l'API è stato eseguito il provisioning dell'hub.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.

Ottieni i dettagli della specifica

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 dell'hub API.

    Vai all'hub API
  2. Fai clic su API.
  3. Individua l'API con la versione contenente la specifica che vuoi controllare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco di API. Se necessario, utilizza la ricerca per individuare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione da controllare.
  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 Ottieni i dettagli della specifica:

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 dell'hub API. Il progetto host è stato selezionato quando è stato eseguito il provisioning dell'hub API.
  • HUB_LOCATION: la posizione del progetto host. La località è stata scelta quando l'API è stato eseguito il provisioning dell'hub.
  • 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"
}

Elimina una specifica API

Questa sezione spiega come eliminare una specifica API da una versione. Se elimini una specifica, verranno eliminate anche le 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 all'hub API
  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 da 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 dell'hub API. Il progetto host è stato selezionato quando è stato eseguito il provisioning dell'hub API.
  • HUB_LOCATION: la posizione del progetto host. La località è stata scelta quando l'API è stato eseguito il provisioning dell'hub.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.
  • SPEC_ID: l'ID univoco della specifica da eliminare.

Modifica metadati della specifica

Puoi modificare alcuni dei metadati associati a una specifica archiviata nell'hub API. 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 dell'hub API.

    Vai all'hub API
  2. Fai clic su API.
  3. Individua l'API con la versione contenente le specifiche che vuoi modificare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco delle 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: seleziona un nuovo file delle specifiche da caricare.
    • 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 località 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.

Visualizza i risultati 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 dell'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 delle API. Se necessario, utilizza la ricerca per individuare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione contenente la specifica da controllare.
  6. Fai clic su Risultati nella colonna Lint per visualizzare i risultati del lint.

Ottieni contenuti della specifica

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

Console

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

  1. Nella console Google Cloud, vai alla pagina dell'hub API.

    Vai all'hub API
  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 delle 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 Base64 di una specifica API che è stata caricata nell'hub API. Utilizza l'API Ottieni contenuti della specifica:

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 dell'hub API. Il progetto host è stato selezionato quando è stato eseguito il provisioning dell'hub API.
  • HUB_LOCATION: la posizione del progetto host. La località è stata scelta quando l'API è stato eseguito il provisioning dell'hub.
  • 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"
}