Come aggiornare le API del portale per sviluppatori Apigee

Introduzione

Apigee è una piattaforma di gestione delle API che offre un portale per sviluppatori integrato per la documentazione degli endpoint esposti nei proxy API. Ciò consente agli sviluppatori di interagire facilmente con un'API e di familiarizzare senza troppa complessità.

Tutte le API sono soggette a modifiche e, pertanto, il Portale per sviluppatori Apigee deve essere modificato per riflettere questi aggiornamenti. Tuttavia, l'aggiornamento manuale delle specifiche API diventa rapidamente un'attività complessa.

Questo articolo spiega come automatizzare il processo di aggiornamento delle API in Apigee.

Prerequisiti

• Portale per sviluppatori Apigee

Aggiornamento automatizzato delle API del portale per sviluppatori Apigee

Sono necessarie tre cose per far apparire una specifica API nel Portale per sviluppatori Apigee:

• La specifica Open API , denominato in breve il file delle specifiche. Nel nostro caso stiamo utilizzando il classico Pet Store.
• Un prodotto API – questa è una raccolta di API. Poiché il portale per sviluppatori Apigee funziona con loro, ne creeremo uno per visualizzare le nostre API. A scopo dimostrativo, il nostro prodotto API avrà una sola API.
• Un portale per sviluppatori esistente per pubblicare o aggiornare il Prodotto e le specifiche API.

Le sezioni seguenti spiegano come automatizzare il processo di aggiornamento delle API su Apigee.

Passaggio 1:caricamento di una specifica API

Attualmente, Apigee non fornisce alcun mezzo per caricare una specifica API tramite l'API di amministrazione. Utilizza l'interfaccia utente di Apigee per aggiungere o aggiornare le specifiche dell'API.

1. Seleziona il File di importazione opzione per importare la specifica Pet Store. Tieni aperto Chrome DevTools (o equivalente) mentre lo fai.

2. Dovresti vedere la specifica API (in questo esempio, "negozio di animali") elencata, come nell'immagine qui sotto.

3. La specifica API è stata caricata correttamente. Vediamo cosa è successo in background facendo riferimento alla Rete scheda in Chrome DevTools.

Sono necessarie al massimo tre chiamate API per aggiungere una specifica API:

• POST
• PUT
• GET

POST, PUT e GET chiamate API

Di seguito è riportata la prima chiamata API:

POST https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc

{
  "folder": "173137",
  "kind": "Doc",
  "name": "petstore"
}

• folder :l'ID della cartella delle specifiche della tua organizzazione. Sarà sempre lo stesso poiché ogni organizzazione ha una cartella delle specifiche e non cambia mai.
• kind :In questo caso sarà sempre Doc poiché stiamo caricando un documento.
• name :il nome della specifica API. Sebbene non sia imposto, utilizza un nome univoco, altrimenti può creare confusione durante la visualizzazione delle specifiche dell'API.

Il risultato di questa chiamata è la creazione di una specifica API vuota con il nome specificato. La risposta prevista da Apigee è la seguente:

{
	"id": "299536",
	"kind": "Doc",
	"name": "petstore",
	"created": "2020-06-05T13:24:07.977Z",
	"creator": "/orgs/lukeb-eval",
	"modified": "2020-06-05T13:24:07.977Z",
	"permissions": null,
	"self": "/organizations/lukeb-eval/specs/doc/299536",
	"content": "/organizations/lukeb-eval/specs/doc/299536/content",
	"contents": null,
	"folder": "/organizations/lukeb-eval/specs/folder/173137",
	"folderId": "173137",
	"body": null,
	"trashed": false
}

Prendi nota dell'id . Lo userai nella seguente chiamata per dire ad Apigee in quale file dobbiamo inserire il nostro contenuto:

PUT https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc/299536/content

Il corpo della richiesta per questa chiamata è l'intera specifica API YAML. In risposta, Apigee risponderà con un 200 OK , segnalando che la specifica API è stata caricata correttamente.

L'ultima chiamata è:

GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home

Produce la seguente risposta:

{
	"id": "173137",
	"kind": "Folder",
	"name": "/orgs/lukeb-eval root",
	"created": "2019-06-06T07:39:58.805Z",
	"creator": "/orgs/lukeb-eval",
	"modified": "2019-06-06T07:39:58.805Z",
	"permissions": null,
	"self": "/organizations/lukeb-eval/specs/folder/173137",
	"content": null,
	"contents": [{
		"id": "299536",
		"kind": "Doc",
		"name": "petstore",
		"created": "2020-06-05T13:24:07.977Z",
		"creator": "/orgs/lukeb-eval",
		"modified": "2020-06-05T13:24:08.740Z",
		"permissions": null,
		"self": "/organizations/lukeb-eval/specs/doc/299536",
		"content": "/organizations/lukeb-eval/specs/doc/299536/content",
		"contents": null,
		"folder": "/organizations/lukeb-eval/specs/folder/173137",
		"folderId": "173137",
		"body": null,
		"trashed": false
	}],
	"folder": null,
	"folderId": null,
	"body": null,
	"trashed": false
}

A questo punto, sappiamo che i file delle specifiche sono disponibili nella nostra organizzazione. Questa è l'ultima chiamata eseguita perché Apigee deve aggiornare l'interfaccia utente per mostrare le specifiche più recenti dopo averne aggiunto una nuova.

Questa chiamata viene eseguita anche se apriamo le Specifiche scheda in Apigee.

Dopo aver esaminato le richieste HTTP, ora siamo in grado di automatizzare la creazione o l'aggiornamento di una specifica:

• GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home – Questo ci fornisce il folderId . Ne abbiamo bisogno per la chiamata successiva. Indica anche se la specifica deve essere creata o aggiornata, a seconda che esista già.
• POST https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc – Se la specifica non esiste, eseguiamo questa chiamata per creare un file vuoto.
• PUT https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc/299536/content – Compila le specifiche con le informazioni più recenti. A seconda che si trattasse di una richiesta di creazione o aggiornamento, l'id delle specifiche può essere recuperato dai passaggi 1 o 2.

Questi passaggi si riflettono nel nostro script di automazione upload_spec.py . Questo script richiede i seguenti argomenti per essere eseguito correttamente:

• name – Il nome della specifica che verrà caricata su Apigee. Se questo non è univoco, la specifica con lo stesso nome in Apigee verrà aggiornata.
• file – Il percorso del file delle specifiche sulla tua macchina.
• org – Il nome dell'organizzazione in Apigee. https://apigee.com/organizations/johnd-eval/proxies ha il nome dell'organizzazione johnd-eval .
• username – Il nome utente dell'utente Apigee utilizzato dallo script per recuperare un token di accesso. Questo token di accesso viene utilizzato per tutte le chiamate REST eseguite dallo script. Il token di accesso scade ogni 12 ore. Di solito qui viene utilizzato un utente di automazione dedicato.
• password – La password per il nome utente sopra menzionato.

Per creare o aggiornare le specifiche per l'esempio discusso sopra, usa:

upload_spec.py --name petstore --file petstore.yaml --org lukeb-eval --username $APIGEE_USER --password $APIGEE_PASSWORD

Un tipico risultato di successo, tratto dalla nostra pipeline di automazione, sarebbe il seguente:

Fase 2:caricamento di un prodotto API

Nel nostro sforzo di automazione, abbiamo creato upload_product.py , che sfrutta l'API di gestione di Apigee per creare o aggiornare un prodotto API.

I seguenti argomenti sono necessari affinché lo script venga eseguito correttamente:

• file – Un file JSON che rappresenta il prodotto API da creare. Un esempio di come crearlo può essere trovato nella sezione Crea prodotto API o Aggiorna prodotto API della documentazione API di Apigee Management. Il nome è sempre obbligatorio nel file JSON poiché viene utilizzato per verificare se il prodotto API esiste o meno. Se il prodotto API esiste, viene aggiornato con il nuovo file JSON.
• org – Il nome dell'organizzazione in Apigee.
• username – Il nome utente dell'utente Apigee utilizzato dallo script per recuperare un token di accesso.
• password – La password per il nome utente sopra menzionato.

Può essere eseguito come segue:

upload_api_product.py --file product_settings.json --org lukeb-eval --username $APIGEE_USER --password $APIGEE_PASSWORD

Un tipico risultato di successo, tratto dalla nostra pipeline di automazione, sarebbe il seguente:

Fase 3:caricamento di una specifica API sul portale per sviluppatori

L'aggiornamento di una specifica API non significa che Apigee Developer Portal mostrerà automaticamente quella più recente e Apigee non lo offre tramite la propria API di gestione.

Questa operazione può essere eseguita manualmente tramite l'interfaccia utente, quindi è necessario esaminare quali chiamate API vengono utilizzate per creare o aggiornare la documentazione API sul Portale per sviluppatori.

1. Nelle API sezione del portale selezionato in Apigee, fai clic su +API pulsante:

2. Seleziona il prodotto API e le specifiche API. Infine, aggiungi un nome e una descrizione per l'API e fai clic su Fine .

3. Premendo Fine il pulsante richiede la seguente chiamata HTTP:

POST https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs

{
	"title": "Pet Store",
	"description": "",
	"edgeAPIProductName": "Pet Store",
	"visibility": true,
	"anonAllowed": true,
	"requireCallbackUrl": false,
	"specId": "petstore",
	"specContent": "299536"
}

4. Per visualizzare le specifiche API nel portale, sono necessari i seguenti parametri:

• edgeAPIProductName – Il nome del prodotto API precedentemente creato.
• specId – Il nome della specifica precedentemente creata.
• specContent – L'ID file della specifica creata in precedenza

In modo confuso, il specId è in realtà il nome della specifica e la sua unicità non è imposta da Apigee. Nel nostro script di automazione, assumiamo che la specifica abbia un nome univoco e questo aiuterà a recuperare il specContent tramite il specId più avanti.

Consideriamo cosa fa l'interfaccia utente di Apigee quando una specifica cambia. Se le specifiche del negozio di animali vengono aggiornate, nella schermata delle API nel Portale per sviluppatori verrà visualizzato quanto segue:

Facendo clic su Gestisci istantanea specifica immagine gialla a destra, otteniamo la seguente schermata:

Fai clic su Aggiorna istantanea . Questo aggiorna il Portale per sviluppatori con le ultime specifiche.

Automatizzazione delle richieste API

Per automatizzare il processo, abbiamo bisogno di tre richieste API:

GET https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs

Il primo, produce la seguente risposta:

{
	"status": "success",
	"message": "all visible apidocs returned",
	"data": [{
		"id": 57782,
		"siteId": "lukeb-eval-portal",
		"title": "Pet Store",
		"description": "Pet Store Description",
		"visibility": true,
		"enrollment": null,
		"apiId": "pet-store",
		"edgeAPIProductName": "Pet Store",
		"specId": "petstore",
		"specContent": "299536",
		"specTitle": null,
		"snapshotExists": true,
		"snapshotModified": 1591371293000,
		"modified": 1591371290000,
		"anonAllowed": true,
		"imageUrl": null,
		"snapshotState": "OK_DOCSTORE",
		"requireCallbackUrl": false,
		"categoryIds": [],
		"productExists": true,
		"specModified": null,
		"snapshotOutdated": false,
		"snapshotSourceMissing": false
	}],
	"request_id": "1309320113",
	"error_code": null
}

Dal punto di vista dell'automazione, questa richiesta fornisce l'ID del portale per sviluppatori ed elenca tutte le specifiche del portale.

Dopo aver ottenuto l'ID portale, è necessaria la seguente chiamata API:

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782

{
	"specId": "petstore",
	"imageUrl": null,
	"visibility": true,
	"anonAllowed": true,
	"description": "Pet Store Description"
}

La suddetta chiamata viene utilizzata per confermare la configurazione di base dell'API sul portale. L'ID 57782 alla fine dell'URL della richiesta c'è l'ID del Portale per gli sviluppatori.

Al termine, viene eseguita un'altra richiesta:

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782/snapshot

Questa richiesta non ha un corpo e indica al Portale per sviluppatori di visualizzare le specifiche più recenti.

Con tutte queste informazioni, ora siamo in grado di automatizzare la distribuzione delle specifiche del portale come segue:

1. Usa GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home per assicurarci che le specifiche che vogliamo mostrare esistano.

2. Includi GET https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs per ottenere l'ID del portale e verificare se è necessario creare o aggiornare le specifiche nel portale.

• Se devi creare:

POST https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs

• Se devi aggiornare:

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782/snapshot

A tal fine, il upload_portal_documentation.py è stato creato lo script di automazione. Ciò richiede i seguenti parametri:

• file – File JSON che rappresenta la documentazione del portale API da creare. Un esempio di JSON è mostrato in precedenza in questo post. Da orgname e specId sono forniti come parametri, non dovrebbero far parte del file JSON, altrimenti verranno sovrascritti. specContent viene recuperato da specId a condizione, poiché stiamo lavorando sulla premessa che il nome di una specifica sarà sempre univoco.
• portal – Nome completo del portale dove vogliamo creare la documentazione. per esempio. Se si accede a un portale tramite https://johnd-eval-test.apigee.io, il nome completo del portale è johnd-eval-test .
• org – Come in upload_spec.py .
• username – Come in upload_spec.py .
• password – Come in upload_spec.py .

Può essere eseguito come segue:

upload_portal_documentation.py --file portal_documentation_setup.json --org lukeb-eval --spec_name petstore --portal portal --username $APIGEE_USER --password $APIGEE_PASSWORD

Un tipico risultato di successo, tratto dalla nostra pipeline di automazione, sarebbe il seguente:

Fase 4:integrazione della pipeline CI/CD

Abbiamo questi script in un'immagine Docker, quindi è molto facile importarli ed eseguirli nella pipeline CI/CD.

Prendiamo ad esempio GitLab:

apigee-spec-deploy:
  image: ghcr.io/phoenixnap/apigee-automation:v1.0.0
  stage: spec-deploy
  variables:
    SPEC_NAME: petstore
    SPEC_PATH: petstore.yaml
    APIGEE_PRODUCT: product.json
    APIGEE_PORTAL_DOC: portal_documentation.json
  script:
    - /automation/upload_spec.py --name $SPEC_NAME --file $SPEC_PATH --org $ORG_NAME --username $APIGEE_USER --password $APIGEE_PASSWORD
    - /automation/upload_api_product.py --file $APIGEE_PRODUCT --org $ORG_NAME --username $APIGEE_USER --password $APIGEE_PASSWORD
    - /automation/upload_portal_documentation.py --file $APIGEE_PORTAL_DOC --org $ORG_NAME --spec_name $SPEC_NAME --portal $APIGEE_PORTAL --username $APIGEE_USER --password $APIGEE_PASSWORD

Abbiamo creato un processo di pipeline chiamato apigee-spec-deploy , che estrae l'immagine apigee-automation da GitHub Packages ed esegue i tre script Python di cui abbiamo discusso qui con i parametri necessari.

Il lavoro GitLab interromperà l'esecuzione se uno script non riesce. Se ciò si verifica, nell'output viene fornito un errore dettagliato. Ciò garantisce che ogni volta che uno script viene eseguito, tutte le informazioni necessarie dagli script precedenti saranno disponibili.