Kom igang med MREG-API'et

Autentisere

Man starter med å autentisere seg og motta et "token", slik:

curl -X POST -H "Content-Type: application/json" \
  --data "{\"username\":\"oyvihag-drift\",\"password\":\"$MYPASS\"}" \
  https://mreg.uio.no/api/token-auth/

• Metode POST
• Send med riktig content-type-header (application/json)
• Send en JSON-struktur med brukernavn og passord som postdata
• Husk å logge inn med driftsbruker hvis du trenger skriverettigheter

Du skal få tilbake et token:

{"token":"3c0b19cdef12384762384abcbdfbad76325"}

(Strengen som vises her er ikke et ekte token, bare et eksempel på hvordan det kan se ut)

Du bruker token-verdien til autentisering i videre API-kall.

Hente ut informasjon

APIet returnerer data i JSON-format.

Her er et eksempel som henter ut data om en gitt maskin:

curl -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
   "https://mreg.uio.no/api/v1/hosts/callisto.uio.no"

• Http-metode GET
• Send med http header "Authorization" med verdi "Token " + ditt token
• Maskinnavnet i urlen

Tips: Hvis du bruker curl fra kommandolinjen kan du bruke jq til å formattere outputen:

curl -s -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
   "https://mreg.uio.no/api/v1/hosts/callisto.uio.no" | jq .

Lister og sidetall

Slik henter du en liste over alle maskiner:

curl -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
   "https://mreg.uio.no/api/v1/hosts/"

Obs! I utgangspunktet får du de 100 første, og så kan du be om "neste side" slik:

https://mreg.uio.no/api/v1/hosts/?page=2

Lenker til neste/forrige side finner du også i resultat-jsonen.

Du kan også endre sidestørrelsen til noe annet enn 100, men det er maks oppad begrenset til 1000:

https://mreg.uio.no/api/v1/hosts/?page_size=1000

Filtrering

# alle hoster med navn som starter på "nisse"
https://mreg.uio.no/api/v1/hosts/?name__startswith=nisse

# alle hoster med navn som ender på "ifi.uio.no"
https://mreg.uio.no/api/v1/hosts/?name__endswith=ifi.uio.no

# alle hoster med navn som matcher en regex
https://mreg.uio.no/api/v1/hosts/?name__regex=blue.*educloud

# alle hoster i en liste du oppgir
https://mreg.uio.no/api/v1/hosts/?name__in=saruman.uio.no,sauron.uio.no

Andre typer data

Eksemplene overfor er for hoster, men metodene fungerer noenlunde likt for alle de andre datatypene i Mreg også.

Her er en liste over de mest nyttige endepunktene du kan bruke:

For en fullstendig liste over alle endepunkter som er tilgjengelige, se i kildekoden her og her.

Lage host-objekter

Slik oppretter du et host-objekt:

curl -D - -X POST \
     -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
     -H "Content-Type: application/json" \
     --data '{"name":"minmaskin.uio.no",
        "ipaddress":"123.123.123.123",
        "contact":"oyvind.hagberg@usit.uio.no",
        "comment":"bare en test"}' \
     https://mreg.uio.no/api/v1/hosts/

• Metode POST
• Send med http header "Authorization" med verdi "Token " + ditt token
• Husk riktig content-type
• Post data skal være en JSON-struktur som må inneholder minimum "name", "contact" og "comment"

Sjekk http-statusverdien for å se om kallet gikk bra. Du skal få 201 Created hvis alt gikk bra.

Endre kontaktinfo og kommentar

Hvis du prøver en http post til /api/v1/hosts/.... tolkes det som at du forsøker å opprette et nytt host-objekt. Da får du feilmelding om at "name already in use". Derfor, hvis du vil endre på et objekt, må du bruke patch-metoden.

Kommandoen "host set_comment" i mreg-cli tilsvarer en http patch til /api/v1/hosts/hostnavn.uio.no med body { "comment": "ny kommentar" }.
"host set_contact" blir da en tilsvarende forespørsel bare med "contact" i body. Man kan også sette begge feltene i samme forespørsel.
Eksempel:

curl -D - -X PATCH \
 -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
 -H "Content-Type: application/json" \
 --data '{"contact":"nykontaktadresse@uio.no",
          "comment":"Ny kommentar"}' \
 https://mreg.uio.no/api/v1/hosts/minmaskin.uio.no

HTTP/1.1 204 No Content
...

Feltet contact kan ikke være flere email-adresser dessverre, kun én. Verdien valideres, så den må se ut som en ekte email-adresse eller være tom.
Http-statuskoden som du får tilbake skal være noe i 200-serien hvis operasjonen gikk bra.

Tips: For å endre navnet på en host kan du gjøre en patch til /api/v1/hosts/gammeltnavn.uio.no med body { "name": "nyttnavn.uio.no" }.

Legge til og fjerne roller på maskiner

Legge til en rolle (host policy) på en maskin:

curl -D - -X POST \
     -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
     -H "Content-Type: application/json" \
     --data '{"name":"hostnavn.uio.no"}' \
     'https://mreg.uio.no/api/v1/hostpolicy/roles/ROLLENAVN/hosts/'

HTTP/1.1 201 Created
Server: nginx/1.16.1
...

• Oppgi hostnavnet i JSON.
• Rollen/hostpolicyen legges i urlen. Rollen må selvsagt finnes fra før av i Mreg.
• POST metode, og husk Content-Type header
• Sjekk http-statuskoden som du får tilbake. Skal være 201 hvis operasjonen gikk bra.

Fjerne en maskin fra en rolle/hostpolicy:

curl -D - -X DELETE \
     -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
     'https://mreg.uio.no/api/v1/hostpolicy/roles/ROLLENAVN/hosts/hostnavn.uio.no'

HTTP/1.1 204 No Content

• DELETE metode. Du sender ikke med noe innhold, så du trenger ikke content-type-headeren her.
• Kontroller at du får http status 204 i retur, det betyr at operasjonen gikk bra.

Videre

Vi kommer til å skrive mer på dette dokumentet etterhvert som behovet melder seg. Send gjerne epost til usit-dia@usit.uio.no om hva du ønsker dokumentert.