REST API til IP-adresser og subnet – dokumentation

Grundlæggende

Basis-URL: https://ipmanager.no/api/v1
Alle forespørgsler og svar er JSON (Content-Type: application/json).
Godkendelse med API-nøgle i headeren Authorization: Bearer ipm_….
Alle ændringer via API'et logges i revisionsloggen med nøglens navn som udfører.

API-nøgler og adgange

Nøgler oprettes af en administrator under Automatisk registrering og API. Nøglen vises kun én gang. Hver nøgle har én adgang:

Adgang	Kan
`read`	Læse adresser, subnet og søgning (GET)
`write`	Alt, hvad `read` kan, plus oprette, ændre 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

Endpoints

Metode	Sti	Beskrivelse
GET	`/addresses`	Vis adresser. Parametre: `q`, `status`, `subnet`, `limit`, `offset`
POST	`/addresses`	Opret en adresse
GET	`/addresses/{id}`	Hent én adresse
PATCH	`/addresses/{id}`	Ændr felter på en adresse
DELETE	`/addresses/{id}`	Slet en adresse
GET	`/subnets`	Vis subnet
POST	`/subnets`	Opret et subnet
GET	`/subnets/{id}`	Hent ét subnet
PATCH	`/subnets/{id}`	Ændr et subnet
DELETE	`/subnets/{id}`	Slet et subnet (adresserne bevares)
GET	`/subnets/{id}/next-free`	Næste ledige IPv4-adresse i subnettet
GET	`/search?q=`	Samme søgning som i brugerfladen, inklusive filtre
POST	`/agent/report`	Rapport fra agent eller indsamler
GET	`/agent/dns/targets?cidr=`	Registrerede adresser med værtsnavn, der skal DNS-tjekkes (adgang agent eller read)
POST	`/agent/dns/report`	Resultat af DNS-tjek fra indsamleren
GET	`/conflicts`	Vis afvigelser
POST	`/conflicts/{id}`	Behandl en afvigelse (kvittér eller løs)

Adressefelter

Felt	Type	Bemærkning
`ip`	tekst	IPv4 eller IPv6. Påkrævet ved oprettelse
`status`	tekst	`used`, `free`, `reserved`, `dhcp`, `offline` eller `deprecated`. Standard `used`
`hostname`	tekst	Gemmes med små bogstaver
`mac`	tekst	Alle almindelige skrivemåder, gemmes som `aa:bb:cc:dd:ee:ff`
`device`, `device_type`	tekst	Enhed og enhedstype
`room`, `department`, `site`, `owner`	tekst	Placering og ansvar
`description`	tekst	Fritekst
`tags`	liste	For eksempel `["server", "produktion"]`
`custom`	objekt	Egne felter, for eksempel `{"rack": "A12"}`
`subnet_id`	uuid	Sættes automatisk til det mest specifikke subnet
`source`, `last_seen_at`	–	Kilde (manual, import, agent, scan, api) og sidst set
`created_at`, `updated_at`	tid	ISO 8601

Eksempler

Opret 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":["printer"]}'

Ændr 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":"Udskiftes uge 42"}'

Opret et subnet

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 bygning C","vlan":31,"gateway":"10.20.4.1"}'

Næste ledige IP

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

Søg 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 indsamlere bruger POST /agent/report med en nøgle med adgangen agent. En agent rapporterer sine egne interfaces:

Fra en agent

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

Fra en indsamler

{
  "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-tjek

Indsamleren henter først, hvad der skal tjekkes, og rapporterer derefter resultatet. Se automatisk registrering.

Hent adresser, der skal tjekkes

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" } ] }

Rapportér 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 }

Afvigelser

GET /conflicts viser organisationens afvigelser, som dubleret IP, forkert eller flyttet MAC og DNS-afvigelser, med alvorlighed (critical, warning, info). POST /conflicts/{id} bruges til at kvittere for eller løse en afvigelse. Alle ændringer logges i revisionsloggen.

Fejl

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

Status	Typiske koder	Betyder
400 / 422	`invalid_ip`, `invalid_cidr`, `invalid_mac`, `invalid_status`, `invalid_vlan`, `gateway_outside`	Ugyldige data i forespørgslen
401	`unauthorized`, `invalid_token`	Manglende eller ugyldig nøgle
403	`insufficient_scope`, `forbidden`, `ip_limit_reached`	Nøglen har ikke adgang, eller adressegrænsen er nået
404	`not_found`	Findes ikke i din organisation
409	`duplicate_ip`, `duplicate_subnet`	Adressen eller subnettet findes allerede