REST API for IP-adresser og subnett – dokumentasjon

Grunnleggende

Base-URL: https://ipmanager.no/api/v1
Alle forespørsler og svar er JSON (Content-Type: application/json).
Autentisering med API-nøkkel i headeren Authorization: Bearer ipm_….
Alle endringer via API-et logges i revisjonsloggen, med nøkkelens navn som utfører.

API-nøkler og tilganger

Nøkler lages under Auto-deteksjon og API av en administrator. Nøkkelen vises bare én gang. Hver nøkkel har én tilgang:

Tilgang	Kan
`read`	Lese adresser, subnett og søk (GET)
`write`	Alt `read` kan, pluss opprette, endre og slette
`agent`	Kun sende agentrapporter (`POST /agent/report`)

Eksempel

curl -H "Authorization: Bearer $IPM_TOKEN" https://ipmanager.no/api/v1/search?q=10.20.3

Endepunkter

Metode	Sti	Beskrivelse
GET	`/addresses`	List adresser. Parametre: `q`, `status`, `subnet`, `limit`, `offset`
POST	`/addresses`	Opprett en adresse
GET	`/addresses/{id}`	Hent én adresse
PATCH	`/addresses/{id}`	Endre felter på en adresse
DELETE	`/addresses/{id}`	Slett en adresse
GET	`/subnets`	List subnett
POST	`/subnets`	Opprett et subnett
GET	`/subnets/{id}`	Hent ett subnett
PATCH	`/subnets/{id}`	Endre et subnett
DELETE	`/subnets/{id}`	Slett et subnett (adressene beholdes)
GET	`/subnets/{id}/next-free`	Neste ledige IPv4-adresse i subnettet
GET	`/search?q=`	Samme søk som i grensesnittet, inkludert filtre
POST	`/agent/report`	Rapport fra agent eller innsamler
GET	`/agent/dns/targets?cidr=`	Registrerte adresser med vertsnavn som skal DNS-sjekkes (tilgang agent eller read)
POST	`/agent/dns/report`	Resultat av DNS-sjekk fra innsamleren
GET	`/conflicts`	List avvik
POST	`/conflicts/{id}`	Behandle et avvik (kvitter ut eller løs)

Adressefelter

Felt	Type	Merknad
`ip`	tekst	IPv4 eller IPv6. Påkrevd ved opprettelse
`status`	tekst	`used`, `free`, `reserved`, `dhcp`, `offline` eller `deprecated`. Standard `used`
`hostname`	tekst	Lagres med små bokstaver
`mac`	tekst	Alle vanlige skrivemåter, lagres som `aa:bb:cc:dd:ee:ff`
`device`, `device_type`	tekst	Maskin og maskintype
`room`, `department`, `site`, `owner`	tekst	Plassering og ansvar
`description`	tekst	Fritekst
`tags`	liste	For eksempel `["server", "produksjon"]`
`custom`	objekt	Egne felt, for eksempel `{"rack": "A12"}`
`subnet_id`	uuid	Settes automatisk til mest spesifikke subnett
`source`, `last_seen_at`	–	Kilde (manual, import, agent, scan, api) og sist sett
`created_at`, `updated_at`	tid	ISO 8601

Eksempler

Opprett en adresse

curl -X POST https://ipmanager.no/api/v1/addresses \
  -H "Authorization: Bearer $IPM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip":"10.20.3.41","hostname":"pr-b215","status":"used","room":"B2.15","tags":["skriver"]}'

Endre en adresse

curl -X PATCH https://ipmanager.no/api/v1/addresses/{id} \
  -H "Authorization: Bearer $IPM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"deprecated","description":"Byttes ut uke 42"}'

Opprett et subnett

curl -X POST https://ipmanager.no/api/v1/subnets \
  -H "Authorization: Bearer $IPM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cidr":"10.20.4.0/24","name":"Elever bygg C","vlan":31,"gateway":"10.20.4.1"}'

Neste ledige IP

curl -H "Authorization: Bearer $IPM_TOKEN" \
  https://ipmanager.no/api/v1/subnets/{id}/next-free

Søk med filtre

curl -G https://ipmanager.no/api/v1/search \
  -H "Authorization: Bearer $IPM_TOKEN" \
  --data-urlencode 'q=status:free in:10.20.0.0/16'

Agentrapport

Agenter og innsamlere bruker POST /agent/report med en nøkkel med tilgangen agent. En agent rapporterer egne grensesnitt:

Fra en agent

{
  "hostname": "srv01",
  "os": "Linux",
  "interfaces": [
    { "name": "eth0", "ip": "10.0.0.5", "mac": "00:11:22:33:44:55" }
  ]
}

Fra en innsamler

{
  "source": "scan",
  "hosts": [
    { "ip": "10.0.0.7", "hostname": "printer-2", "mac": "aa:bb:cc:dd:ee:ff" }
  ]
}

Svar

{ "created": 1, "updated": 0, "unchanged": 3, "limited": 0, "errors": [] }

DNS-sjekk

Innsamleren henter først hva som skal sjekkes, og rapporterer så resultatet. Se auto-deteksjon.

Hent adresser som skal sjekkes

curl -G https://ipmanager.no/api/v1/agent/dns/targets \
  -H "Authorization: Bearer $IPM_TOKEN" \
  --data-urlencode 'cidr=10.20.0.0/16'

{ "suffix": "skole.local", "targets": [ { "ip": "10.20.0.11", "hostname": "fil01" } ] }

Rapporter resultatet

POST /api/v1/agent/dns/report
{
  "resolver": "10.20.0.2",
  "results": [
    { "ip": "10.20.0.11", "ptr": ["fil01.skole.local"], "forward": ["10.20.0.11"], "forward_checked": true }
  ]
}

{ "checked": 1, "ok": 1, "problems": 0, "unknown": 0 }

Avvik

GET /conflicts lister organisasjonens avvik, som duplikat IP, feil eller flyttet MAC og DNS-avvik, med alvorlighetsgrad (critical, warning, info). POST /conflicts/{id} brukes til å kvittere ut eller løse et avvik. Alle endringer logges i revisjonsloggen.

Feil

Feil returneres med en HTTP-statuskode og et JSON-objekt: {"error": "kode", "detail": "…"}.

Status	Typiske koder	Betyr
400 / 422	`invalid_ip`, `invalid_cidr`, `invalid_mac`, `invalid_status`, `invalid_vlan`, `gateway_outside`	Ugyldige data i forespørselen
401	`unauthorized`, `invalid_token`	Mangler eller ugyldig nøkkel
403	`insufficient_scope`, `forbidden`, `ip_limit_reached`	Nøkkelen har ikke tilgang, eller adressegrensen er nådd
404	`not_found`	Finnes ikke i din organisasjon
409	`duplicate_ip`, `duplicate_subnet`	Adressen eller subnettet finnes allerede