Nutanix API-versjoner

Relatert

Hva er det og hva gjør de enkelte?

Når man diskuterer Nutanix APIer er det viktig å ta i betraktning alle de forskjellige versjonene som er tilgjengelig. La oss ta en titt på de versjonene som er tilgjengelige i dag. Som en introduksjon, dette er hvordan Nutanix beskriver disse APIene:

"The Nutanix REST APIs allow you to create scripts that run system administration commands against the Nutanix cluster. The API enables the use of HTTP requests to get information about the cluster as well as make changes to the configuration. Output from the API calls are returned in JSON format. The v2 API is an update of the v1 API. Users of the v1 API are encouraged to migrate to v2.”

Autentisering
Autentisering mot Nutanix REST APIene gjøres ved HTTP Basic Authentication. Forespørsler mot HTTP port 80 blir automatisk videresendt til HTTPS port 443. Dette krever at en gyldig cluster- eller konfigurert Directory Service-identifikasjon blir sendt som del av API-requesten. For å gjennomføre hvilken som helst Nutanix API-request, kreves det minimum READ tilgang. En Cluster Admin-konto kreves ikke for å gjennomføre API-requests, så lenge requesten ikke inneholder direkte handlinger som gjør endringer på clusteret. 


Prism Element “vs” Prism Central
Prism Element APIet er cluster-spesifikt; med andre ord designet for å styre eller endre entiteter i clusteret hvor Prism kjører. Prism Central APIet inkluderer et større sett av APIer for å endre entiteter som ikke nødvendigvis er spesifikt for ett enkelt cluster. 


API Versioner
Fra Januar 2019 finnes det tre offentlig tilgjengelige Nutanix APIer. Merk at selv om man ser API v0.8 listet i REST API Explorer, så er det sterkt anbefalt å bruke v3.0, der hvor det er mulig. Versjonene tilgjengelige blir styrt av Nutanix AOS eller Prism Central versjonen installert. Med tanke på denne artikkelen er informasjonen rundt v0.8 kun ment for å dekke alle versjoner. 

API Versjonene tilgjengelige i dag er følgende: 

  • v1
  • v2.0
  • v3

Obs ang. sikkerhet: I eksemplene under vil du se at -insecure cURL parameteret brukes. Dette brukes kun for å omgå SSL/TLS verifikasjonsproblematikken, som oppstår ved å bruke self-signed sertifikater. Tenk derfor gjennom potensiell sikkerhetsproblematikk og negative konsekvenser ved å unngå denne sjekken i et produksjonsmiljø. Windowsbrukere kan laste ned cURL fra nettsiden til curl. De samme forholdsregler gjelder når man oppgir brukernavn og passord direkte i kommandolinjen. Dette bør unngås der hvor det er mulig, siden denne metoden viser både brukernavn og passord i klartekst. 

Kommentar ang. cURL: cURL blir brukt i denne artikkelen som et enkelt cross-plattform grunnlag for å teste API-requests fra kommandolinjen. Denne måten vil ikke passe alle, og det er mange andre måter å teste API-requests på. For eksempel:

  • Postman, for de som foretrekker en mer grafisk fremstilling.  
  • Invoke-WebRequest, for Windows-brukere som foretrekker PowerShell.
  • Python Interpreter for andre som skriver cross-platform scripts. 


API v1
Status: Tilgjengelig 
Dette settet med APIer ble tilgjengelig (kronologisk) før v0.8 APIet, som ikke dekkes her. Det ble, for eksempel brukt til å endre og vise VMer, storage containers og storage pools. I en periode var v1 og v0.8 APIene eneste muligheten vi utviklere hadde til å programmatisk samhandle med Nutanix-clustere. Noen av API-endpointene kunne bare brukes med AHV hypervisor og noen kunne brukes på tvers av forskjellige hypervisorer (AHV + ESXi). 

Her er et enkelt eksempel på en v1 API request URL for å liste alle storage containers i et cluster: 
> https://<cluster_virtual_ip>:9440/api/nutanix/v1/containers

Alternativt, kan dette HTTPS-kallet kjøres med følgende curl kommando:
> curl -X GET \
> 'https://<cluster_virtual_ip>:9440/api/nutanix/v1/containers?=' \
> -H 'Accept: application/json' \
> -H 'Content-Type: application/json' \
> --insecure \
> --basic --user <cluster_username>:<cluster_password>

En av grunnene til å bruke API v1 i dag er å samle ytelsesinformasjon fra enkelte entiteter. For eksempel kan et egendefinert dashbord inneholde lagringsytelse. 


API v2.0
Status: Tilgjengelig
Versjon v1 av APIet fungerte veldig bra. De var (og er fortsatt i noen sammenhenger), måten Prism-grensesnittet henter data fra clusteret. En forenklet forklaring vil være å si at v2 APIene er hvor v0.8 og v1 APIene ble slått sammen. Mange av entitetene og endpointene tilgjengelig i v0.8 og v1 ble tilgjengeliggjort i v2, sammen med en stor del back-end oppryddning og omstrukturering av endpoints. v2 APIene var også de første som offisielt ble tilgjengeliggjort av Nutanix (GA API).

Om du tidligere har benyttet deg av v0.8 og v1 APIene, vil du raskt se en del forskjeller. For eksempel har "containers" byttet navn til "storage_containers" og "storagePools" byttet navn til "storage_pools". Hva er forskjellen? En konsistent navnepolicy i form av "snake-case" for alle entiteter. 

Her er et enkelt eksempel på en v2 API request for å liste alle storage_containers i et cluster: 
> https://<cluster_virtual_ip>:9440/api/nutanix/v2.0/storage_containers

Alternativt, samme HTTPS API request som en curl kommando: 
> curl -X GET \
> https://<cluster_virtual_ip>:9440/api/nutanix/v2.0/storage_containers \
> -H 'Accept: application/json' \
> -H 'Content-Type: application/json' \
> --insecure \
> --basic --user <cluster_username>:<cluster_password>

Rask oppsummering
Før vi fortsetter, merk at alle APIene over returnerer et JSON-reponse som enkelt kan konsumeres av mange programmerings- eller scripting språk. I tillegg er alle requestene over HTTP GET-requests, som ikke krever en payload (POST body).


API v3
Status: Tilgjengelig 
Versjon 3 APIene som ble tilgjengeliggjort for GA 17. April 2018, er den første endringen bort fra hvordan det hadde blitt gjort tidligere. 

Nutanix brukte GET-requests for å hente data fra et cluster og POST for å gjøre endringer - v3 APIet er litt annerledes. Alle de forrige APIene krevde fortsatt at utvikleren fortalte systemet hva det skulle gjøre og hvordan det skulle gjøres. v3 APIene er de første APIene bygget rundt en Intentful-tankegang. Det betyr å flytte programmeringen fra brukeren til maskinen. I stedet for å skrive store mengder kode for å få noe gjort, kan vi fortelle systemet hva ønsket "state" er, og systemet vil selv finne den beste løsningen for å nå målet. Dette høres kanskje kjent ut for de som bruker configuration management-verktøyer som Salt, Chef, Puppet, Ansible, PowerShell DSC osv. 

Hvordan alt dette skjer er for omfattende for denne artikkelen, men se på requestene i eksemplene under. Man får fortsatt lignende informasjon som de tidligere requestene, men med noen få viktige forskjeller. 
Det er en HTTP POST request, ikke en GET. 
En JSON payload (POST body) kreves, så clusteret vet hvilken entitet den skal returnere. I dette eksempelet bruker vi VMer. Vi forteller systemet hva vi vil gjøre med dataen; her listes alle VMer. Denne requesten kan kjøres mot Prism Element og Prism Central uten problemer. 

> https://<prism_central_or_cluster_virtual_ip>:9440/api/nutanix/v3/vms/list

og JSON post body: 
>
> {"kind":"vm"}

Alternativt, kan denne HTTPS API-requesten kjøres som en curl kommando: 

> curl -X POST \
> https://<prism_central_virtual_ip>:9440/api/nutanix/v3/vms/list \
> -H 'Accept: application/json' \
> -H 'Content-Type: application/json' \
> -d '{"kind":"vm"}' \
> --insecure \
> --basic --user <cluster_username>:<cluster_password>

cURL Command Analysis
Som et ekstra steg, la oss kikke på denne API v3 requesten og se hva alle delene av kommandoene gjør.
Hvis du er kjent med cURL for å gjøre API requests, så vil du gjenkjenne det meste.

> curl -X POST \ – Kjør cURL og spesifiser at vi vil starte en HTTP POST request (ikke en HTTP GET).
> https://<prism_central_virtual_ip>:9440/api/nutanix/v3/vms/list \ – Spesifiserer hele URLen å sende API requesten til.
> -H ‘Accept: application/json’ \ – Spesifiserer innholdstyper klienten skjønner.
> -H ‘Content-Type: application/json’ \ – Forteller serveren hvilken type data som faktisk sendes.
> -d ‘{“kind”:”vm”}’ \ – For vår POST request, spesifiseres request "body" med andre ord parameterene som sendes sammen med requesten.
> –insecure \ – Forteller cURL kommandoen at den skal ignorere SSL verifikasjonsfeil (se tidligere kommentar om dette).
> –basic – Forteller cURL kommandoen at vi vil autentisere ved hjelp av "Basic Authentication".
> –user <cluster_username>:<cluster_password> – Spesifiserer brukernavn og passord som skal brukes i Basic Authentication.


Usecaser for de ulike versjonene av APIet
Med det vi nå vet om API-versjonene, la oss se på hvorfor du kanskje vil bruke de ulike. 

v1: Støtte for legacy applikasjoner og cluster-wide ytelsesdata. 
v2.0: Migrering bort fra gamle APIer; kombinasjon av eldre v0.8 APIer i et enkelt GA API. Cluster-spesifikke oppgaver f.eks storage container informasjon og management. 
v3 mot Prism Element: Nyeste supporterte API med mål om å styre cluster-spesifikke entiteter som f.eks VMer. 
v3 mot Prism Central: Nyeste supporterte API med mål om å styre miljøkonfigurasjon og entiteter. I motsettning til API v3 mot Prism Element, inkluderer dette en stor samling av entiteter som for eksempel Calm Blueprints, RBAC, Applikasjoner og Nutanix Flow sikkerhetsregler.


Oppsummering
Nå vet du hvilke tilgjengelige APIer som finnes, og hva forskjellen mellom disse er.
Mer informasjon om APIene finnes i Nutanix Developer API Reference.

nLogic har spisskompetanse innen design, implementering og optimalisering av Nutanix løsninger og hjelper deg i alle faser av anskaffelsen.