API-dokumentasjon

Versjon: v0
Sist oppdatert: 2019-09-24 11:58

Testperiode

Domeneshop tilbyr nå et enkelt REST-basert API for testing. API-tjenesten er foreløpig i versjon 0, og det er sannsynlig at grensesnittet vil forandre seg i løpet av testperioden. Dokumentasjonen på disse sidene kan potensielt være utdatert.

Vi kan ikke garantere for stabiliteten av API-tjenesten i testperioden, og ber derfor kunder om å ikke bruke denne tjenesten til driftskritiske formål.

For å få tilgang til APIet, ta kontakt med kundeservice.

Autentisering

For å benytte deg av dette APIet behøver du innloggingsopplysninger i form av et API-token og en API-secret. Dette er i praksis synonymt med et brukernavn og passord, men muliggjør mer granulær tilgangskontroll for den aktuelle brukerkontoen.

Du kan i dag ikke opprette disse selv. Ta kontakt med kundeservice for å få tilgang.

Foreløpig er eneste autentiseringsmekanisme HTTP Basic Auth. Brukernavnet er ditt API-token, og passordet er din API-secret.

Et eksempel på autentisert forespørsel i cURL ser slik ut:

curl --user "{token}:{secret}" https://api.domeneshop.no/v0/domains

{token} og {secret} er henholdsvis ditt API-token, og din API-secret.

Biblioteker

Domeneshop vedlikeholder flere API-biblioteker får å gjøre det enklere å benytte seg av APIet. Merk at disse bibliotekene har samme stabilitetsgaranti som APIet i testperioden (se Testperiode).

Bibliotekene finner du i vårt Github repository.

Domeneshop vedlikeholder også en modul til EFF’s Certbot, som gjør det enkelt å sette opp automatiske SSL-sertifikater på egen server, for domener som har DNS-tjeneste hos Domeneshop. Denne modulen finner du i vårt Github repository her.

Endepunkter

Følgende endepunkter er definert for versjon 0 av APIet.

Domener

GET Hente alle domenenavn

GET https://api.domeneshop.no/v0/domains

Returnerer 200 OK ved suksess, og i body en liste over alle domenenavn.

Vi aksepterer følgende valgfrie parametere i query string:

Parameter

Forklaring

domain

Filtrerer listen slik at den kun inneholder domenenavn som inneholder denne verdien. For eksempel vil ?domain=.no kun returnere alle domener som inneholder .no i navnet.

Eksempel:

GET https://api.domeneshop.no/v0/domains
HTTP 200 OK
[
  {
    "domain": "example.com",
    "expiry_date": "2019-10-12",
    "id": 1,
    "nameservers": [
      "ns1.hyp.net",
      "ns2.hyp.net",
      "ns3.hyp.net"
    ],
    "registered_date": "2015-10-12",
    "registrant": "Example Registrant",
    "renew": true,
    "services": {
      "dns": true,
      "email": false,
      "registrar": true,
      "webhotel": "none"
    },
    "status": "active"
  }
]

GET Hente informasjon om domenenavn

GET https://api.domeneshop.no/v0/domains/{domainId}

Returnerer 200 OK ved suksess, og i body informasjon om et spesifikt domenenavn.

URL Parameter

Forklaring

domainId

Domenenavnets ID. Kan hentes ut fra URL i kontrollpanelet på våre websider, eller fra API-kallet GET Hente alle domenenavn

Eksempel:

GET https://api.domeneshop.no/v0/domains/1
HTTP 200 OK
{
  "domain": "example.com",
  "expiry_date": "2019-10-12",
  "id": 1,
  "nameservers": [
    "ns1.hyp.net",
    "ns2.hyp.net",
    "ns3.hyp.net"
  ],
  "registered_date": "2015-10-12",
  "registrant": "Example Registrant",
  "renew": true,
  "services": {
    "dns": true,
    "email": false,
    "registrar": true,
    "webhotel": "none"
  },
  "status": "active"
}

DNS

GET Hente alle DNS-pekere for domene

GET https://api.domeneshop.no/v0/domains/{domainId}/dns

Returnerer 200 OK ved suksess, og i body en liste over alle DNS-pekere for domenenavnet.

URL Parameter

Forklaring

domainId

Domenenavnets ID. Kan hentes ut fra URL i kontrollpanelet på våre websider, eller fra API-kallet GET Hente alle domenenavn

Eksempel:

GET https://api.domeneshop.no/v0/domains/1/dns

Respons:

HTTP 200 OK
[
    {
        "data": "127.0.0.1",
        "host": "subdomain",
        "id": 1233,
        "ttl": 3600,
        "type": "A"
    },
    {
        "data": "my-text",
        "host": "subdomain",
        "id": 1234,
        "ttl": 3600,
        "type": "TXT"
    }
]

GET Hente informasjon om DNS-peker for domene

GET https://api.domeneshop.no/v0/domains/{domainId}/dns/{recordId}

Returnerer 200 OK ved suksess, og i body informasjon om en spesifikk DNS-peker for et domene.

URL Parameter

Forklaring

domainId

Domenenavnets ID. Kan hentes ut fra URL i kontrollpanelet på våre websider, eller fra API-kallet GET Hente alle domenenavn

recordId

DNS-pekerens ID. Kan hentes med API-kallet GET Hente informasjon om DNS-peker for domene, eller fra resultatet i POST Opprette DNS-peker for domene

Eksempel:

GET https://api.domeneshop.no/v0/domains/1/dns/1234

Respons:

HTTP 200 OK
{
  "data": "my-text",
  "host": "subdomain",
  "id": 1234,
  "ttl": 3600,
  "type": "TXT"
}

POST Opprette DNS-peker for domene

POST https://api.domeneshop.no/v0/domains/{domainId}/dns

Oppretter en DNS-peker for et domenenavn. Krever et JSON-enkodet objekt i innsendt data (request body).

Returnerer 201 Created ved suksess, og en Location-header med URL til det opprettede objektet. Body er tom.

URL Parameter

Forklaring

domainId

Domenenavnets ID. Kan hentes ut fra URL i kontrollpanelet på våre websider, eller fra API-kallet GET Hente alle domenenavn

Følgende nøkler er definerte for det innsendte JSON-objektet:

JSON Body

Forklaring

type (påkrevd)

DNS-pekerens RR-type. Må være én av: A AAAA CNAME ANAME TLSA MX SRV DS CAA NS TXT.

host (påkrevd)

Vertsnavnet som DNS-pekeren skal gjelde. For rotdomenet, bruk @ eller tom streng «».

data (påkrevd)

Verdi/data. Gyldige verdier avhenger av pekerens RR-type.

ttl

TTL i sekunder.

priority

Påkrevd for MX- og SRV-pekere. Prioritet for pekeren.

weight

Påkrevd for SRV-pekere. En tallverdi som angir vekten til pekeren.

port

Påkrevd for SRV-pekere. Et portnummer for SRV-pekeren.

usage

Påkrevd for TLSA-pekere. TLSA usage. Tallverdi, 1 , 2 eller 3.

selector

Påkrevd for TLSA-pekere. TLSA selector. Tallverdi, 0 eller 1.

dtype

Påkrevd for TLSA-pekere. TLSA matching type. Tallverdi, 0, 1 eller 2.

tag

Påkrevd for DS- og CAA-pekere.

alg

Påkrevd for DS-pekere. Se RFC3658 for detaljer.

digest

Påkrevd for DS-pekere. Se RFC3658 for detaljer.

flags

Påkrevd for CAA-pekere. Se RFC3658 for detaljer.

Eksempel:

POST https://api.domeneshop.no/v0/domains/1/dns/
{"type": "A", "host": "www", "ttl": 3600, "data": "127.0.0.5"}

Respons:

HTTP 201 Created

Location: https://api.domeneshop.no/v0/domains/1/dns/1235

PUT Modifisere eksisterende DNS-peker for domene

PUT https://api.domeneshop.no/v0/domains/{domainId}/dns/{recordId}

Modifiserer en eksisterende DNS-peker for et domenenavn. Krever et JSON-enkodet objekt i innsendt data (request body).

Det er ikke tillatt å endre vertsnavn eller RR-type på en eksisterende DNS-peker. Om dette ønskes, slett den eksisterende DNS-pekeren og opprett en ny.

Returnerer 204 No Content ved suksess. Body er tom.

URL Parameter

Forklaring

domainId

Domenenavnets ID. Kan hentes ut fra URL i kontrollpanelet på våre websider, eller fra API-kallet GET Hente alle domenenavn

recordId

DNS-pekerens ID. Kan hentes med API-kallet GET Hente informasjon om DNS-peker for domene, eller fra resultatet i POST Opprette DNS-peker for domene

Se API-kallet POST Opprette DNS-peker for domene for informasjon om gyldig innsendt data.

Eksempel:

PUT https://api.domeneshop.no/v0/domains/1/dns/1235

{"type": "A", "host": "www", "ttl": 3600, "data": "127.0.0.6"}

Respons:

HTTP 204 No Content

DELETE Slette eksisterende DNS-peker for domene

DELETE https://api.domeneshop.no/v0/domains/{domainId}/dns/{recordId}

Sletter en eksisterende DNS-peker for et domenenavn.

Returnerer 204 No Content ved suksess. Body er tom.

Dersom DNS-pekeren ikke eksisterer, returneres 404 med feilkode resource:unknown.

URL Parameter

Forklaring

domainId

Domenenavnets ID. Kan hentes ut fra URL i kontrollpanelet på våre websider, eller fra API-kallet GET Hente alle domenenavn

recordId

DNS-pekerens ID. Kan hentes med API-kallet GET Hente informasjon om DNS-peker for domene, eller fra resultatet i POST Opprette DNS-peker for domene

Eksempel:

DELETE https://api.domeneshop.no/v0/domains/1/dns/1235

Respons:

HTTP 204 No Content

WWW-videresending

GET Hente alle WWW-videresendinger for domene

GET https://api.domeneshop.no/v0/domains/{domainId}/forwards

Returnerer 200 OK ved suksess, og i body en liste over alle WWW-videresendinger for domenenavnet.

URL Parameter

Forklaring

domainId

Domenenavnets ID. Kan hentes ut fra URL i kontrollpanelet på våre websider, eller fra API-kallet GET Hente alle domenenavn

Eksempel:

GET https://api.domeneshop.no/v0/domains/1/forwards

Respons:

HTTP 200 OK
[
    {
        "host": "www",
        "frame": false,
        "url": "http://example.com"
    },
    {
        "host": "@",
        "frame": false,
        "url": "http://example.com"
    }
]

GET Hente informasjon om WWW-videresending for domene

GET https://api.domeneshop.no/v0/domains/{domainId}/forwards/{host}

Returnerer 200 OK ved suksess, og i body informasjon om en spesifikk WWW-videresending for et domene.

URL Parameter

Forklaring

domainId

Domenenavnets ID. Kan hentes ut fra URL i kontrollpanelet på våre websider, eller fra API-kallet GET Hente alle domenenavn

host

Vertsnavn/subdomene du ønsker informasjon om

Eksempel:

GET https://api.domeneshop.no/v0/domains/1/forwards/www

Respons:

HTTP 200 OK
{
    "host": "www",
    "frame": false,
    "url": "http://example.com"
}

POST Opprette WWW-videresending for domene

POST https://api.domeneshop.no/v0/domains/{domainId}/forwards

Oppretter en WWW-videresending for et domenenavn. Krever et JSON-enkodet objekt i innsendt data (request body).

Returnerer 201 Created ved suksess, og en Location-header med URL til det opprettede objektet. Body er tom.

URL Parameter

Forklaring

domainId

Domenenavnets ID. Kan hentes ut fra URL i kontrollpanelet på våre websider, eller fra API-kallet GET Hente alle domenenavn

Følgende nøkler er definerte for det innsendte JSON-objektet:

JSON Body

Forklaring

host (påkrevd)

Vertsnavn/subdomene for WWW-videresendingen. For å opprette en videresending for rot-domenet, bruk host @

url (påkrevd)

Måladressen som det skal videresendes til

frame

Booleanverdi (true eller false) for hvorvidt videresendingen skal opprettes som en «frame forward». Bruk av frame forwards er ikke anbefalt. Se her for mer informasjon.

Eksempel:

POST https://api.domeneshop.no/v0/domains/1/forwards
{ "host": "www", "frame": false, "url": "http://example.com" }

Respons:

HTTP 201 Created

Location: https://api.domeneshop.no/v0/domains/1/forwards/www

PUT Modifisere eksisterende WWW-videresending for domene

PUT https://api.domeneshop.no/v0/domains/{domainId}/forwards/{host}

Modifiserer en eksisterende WWW-videresending for et domenenavn. Krever et JSON-enkodet objekt i innsendt data (request body).

Det er ikke tillatt å endre vertsnavn eller RR-type på en eksisterende WWW-videresending. Om dette ønskes, slett den eksisterende WWW-videresendingen og opprett en ny.

Returnerer 204 No Content ved suksess. Body er tom.

URL Parameter

Forklaring

domainId

Domenenavnets ID. Kan hentes ut fra URL i kontrollpanelet på våre websider, eller fra API-kallet GET Hente alle domenenavn

host

Vertsnavn/subdomene for WWW-videresendingen. For rot-domenet, bruk host @

Se API-kallet POST Opprette WWW-videresending for domene for informasjon om gyldig innsendt data.

Eksempel:

PUT https://api.domeneshop.no/v0/domains/1/forwards/www

{
    "host": "www",
    "frame": false,
    "url": "http://example.com/"
}

Respons:

HTTP 204 No Content

DELETE Slette eksisterende WWW-videresending for domene

DELETE https://api.domeneshop.no/v0/domains/{domainId}/forwards/{host}

Sletter en eksisterende WWW-videresending for et domenenavn.

Returnerer 204 No Content ved suksess. Body er tom.

Dersom WWW-videresendingen ikke eksisterer, returneres 404 med feilkode resource:unknown.

URL Parameter

Forklaring

domainId

Domenenavnets ID. Kan hentes ut fra URL i kontrollpanelet på våre websider, eller fra API-kallet GET Hente alle domenenavn

host

Vertsnavn/subdomene for WWW-videresendingen. For rot-domenet, bruk host @

Eksempel:

DELETE https://api.domeneshop.no/v0/domains/1/forwards/www

Respons:

HTTP 204 No Content

Faktura

GET Hente alle fakturaer

GET https://api.domeneshop.no/v0/invoices

Returnerer 200 OK ved suksess, og i body en liste over alle fakturaer.

Vi aksepterer følgende valgfrie parametere i query string:

Parameter

Forklaring

status

Filtrerer listen slik at den kun inneholder fakturaer med denne statusen. For eksempel vil ?status=paid kun returnere fakturaer som er markert betalt i våre systemer.

Eksempel:

GET https://api.domeneshop.no/v0/invoices?status=paid
HTTP 200 OK
[
    {
        "amount": 120,
        "currency": "NOK",
        "due_date": "2097-11-14",
        "id": 1,
        "issued_date": "2097-10-30",
        "paid_date": "2098-11-10",
        "status": "paid",
        "type": "invoice",
        "url": "https://domene.shop/invoice?nr=1"
    },
    {
        "amount": 120,
        "currency": "NOK",
        "due_date": "2098-11-14",
        "id": 2,
        "issued_date": "2098-10-30",
        "paid_date": "2098-11-10",
        "status": "paid",
        "type": "invoice",
        "url": "https://domene.shop/invoice?nr=2"
    }
]

GET Hente spesifikk faktura

GET https://api.domeneshop.no/v0/invoices/{invoiceId}

Returnerer 200 OK ved suksess, og i body informasjon om et spesifikt domenenavn.

URL Parameter

Forklaring

invoiceId

Fakturanummeret. Finnes på fakturaen, i kontrollpanelet på våre websider, eller kan hentes fra API-kallet GET Hente alle fakturaer

Eksempel:

GET https://api.domeneshop.no/v0/invoices/1
HTTP 200 OK
{
    "amount": 120,
    "currency": "NOK",
    "due_date": "2097-11-14",
    "id": 1,
    "issued_date": "2097-10-30",
    "paid_date": "2098-11-10",
    "status": "paid",
    "type": "invoice",
    "url": "https://domene.shop/invoice?nr=1"
}

Responsfelter:

Felt

Forklaring

type

Én av invoice eller credit_note

amount

Fakturabeløpet

currency

Valuta fakturaen er utstedt i

due_date

Forfallsdato for fakturaen. Kun tilgjengelig for type invoice

id

Fakturanummeret

issued_date

Dato fakturaen ble utstedt

paid_date

Dato for betaling. Kun tilgjengelig dersom fakturaen er registert betalt (status paid)

status

Fakturastatus. Én av unpaid, paid eller settled

settled er en avregnet kredittnota, disse blir som regel opprettet dersom du fravelger/sier opp et domene fra fakturaen

Se fakturalenken for nærmere spesifikasjon

url

Lenke til den nettbaserte fakturaen

Feilkoder

Her er en oversikt over de definerte feilkodene, og en tilhørende forklaring:

HTTP Status

Feilkode

Forklaring

403

resource:unauthorized

Den innsendte autentiseringsinformasjon har ikke tilgang til den ønskede ressursen. Det kan skyldes at du ikke har tilgang til den angitte domainId, eller at API-tokenet du benytter deg av ikke har de nødvendige rettighetene.

404

resource:unknown

Den ønskede ressursen eksisterer ikke. Det betyr sannsynligvis at angitt domainId eller recordId ikke eksisterer.

403

resource:methodInvalid

HTTP-verbet du forsøker å benytte er ikke støttet for ønsket ressurs.

400

request:jsonInvalid

Innsendt data er ikke et gyldig JSON-objekt.

401

request:headerMissing

Den nødvendige Authorization-headeren mangler i forespørselen.

400

request:headerInvalid

Den nødvendige Authorization-headeren mangler er ikke en gyldig HTTP Basic Auth header.

401

authentication:failed

Authorization er en gyldig HTTP Basic Auth header, men autentisering feilet. token/secret er enten feil, eller tokenet har løpt ut.

400

record:invalid

Det innsendte JSON-objektet er ikke en gyldig DNS-peker. Se API-kallet POST Opprette DNS-peker for domene for informasjon om gyldig innsendt data.

412

record:illegalChange

Ugyldig modifikasjon av DNS-peker. Se PUT Modifisere eksisterende DNS-peker for domene

409

record:collision

Opprettelse av DNS-pekeren vil føre til kollisjon med en eksisterende CNAME-peker.

400

forwarding:invalid

Det innsendte JSON-objektet er ikke en gyldig WWW-videresending. Se API-kallet ref:POST Opprette WWW-videresending for domene for informasjon om gyldig innsendt data.

412

forwarding:illegalChange

Ugyldig modifikasjon av WWW-videresending. Se PUT Modifisere eksisterende WWW-videresending for domene

409

forwarding:collision

Opprettelse av WWW-videresending vil føre til kollisjon med en eksisterende videresending. Det kan kun eksistere én videresending per host.

Support

Ved problemer, spørsmål eller andre tilbakemeldinger, ta kontakt med kundeservice.