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-gid@rt.uio.no om hva du ?nsker dokumentert.