REST DNS-API

Met de REST DNS-API kun je DNS-records op je domeinnaam volledig geautomatiseerd beheren vanuit je eigen software.

Basisgegevens

Voor toegang tot de DNS-API heb je een API-key nodig. Deze kun je bij de isntellingen van je domeinnaam in Mijn NederHost instellen. Iedere domeinnaam heeft een eigen API-key.

• Het basisadres van DNS-API is https://api.nederhost.nl/dns/v1

• De API-key wordt doorgegeven als Bearer-token in een Authorization-header.

• Voor het uitwisselen van de gegevens wordt gebruik gemaakt van JSON.

Methods en endpoints

De DNS-API ondersteunt de volgende HTTP-methods:

GET	gegevens opvragen/query
POST	gegevens vervangen
PATCH	gegevens aanvullen of wijzigen
DELETE	gegevens verwijderen

Afhankelijk van het endpoint is een bepaalde HTTP-method wel of niet toegestaan.

Methods	Endpoint	Omschrijving
GET	/zones/domeinnaam/records	opvragen records van een zone
POST, PATCH, DELETE	/zones/domeinnaam/records/naam/type	wijzigen records van een bepaald type op een bepaalde naam
PATCH, DELETE	/zones/domeinnaam/records_by_id/id	wijzigen van een specifiek record

Hierin is:

• domeinnaam: de volledige domeinnaam die je aan het bewerken bent
• naam: de volledige naam (inclusief domeinnaam) van het record
• type: het type DNS-records, bijvoorbeeld A, CNAME of MX
• id: een interne identifier die je vanuit de API krijgt

Gegevensformaat

De DNS-API accepteert sets van resource records op de endpoints. Bij gebruik van POST wordt de eventuele bestaande set records op de combinatie van naam en type vervangen, bij gebruik van PATCH wordt de set alleen aangevuld met nieuwe gegevens. Een set van resource records bestaat uit een array met daarin voor ieder record een object met de volgende keys die verwijzen naar een string:

• content: de inhoud van het record in standaard representatieformaat (zoals deze in een zonefile zou staan)
• ttl: de in te stellen TTL van het record in seconden (optioneel)
• comment: een opmerking bij het record (optioneel)

De records komen uit de DNS-API als een object met daarin voor ieder label in de zone een key en een object, met in dat object voor ieder type record op dat label een key en een array met daarin de set van resource records in representatieformaat. Zie ook de voorbeelden hieronder voor meer informatie.

Statuscodes

De DNS-API meldt de status terug met HTTP statuscodes. De volgende codes zijn in het bijzonder van belang:

200	Succesvolle query of wijziging met terugmelding nieuwe gegevens
204	Succesvolle wijziging zonder terugmelding
401	Geen API-key opgegeven
403	Onjuiste API-key
404	Onjuiste domeinnaam
500	Interne fout of tijdelijk probleem

In de HTTP-berichten met een statuscode 4xx wordt ook een JSON-object toegevoegd met daarin informatie over de fout en de verwerkte invoer.

Voorbeelden

In onderstaande voorbeelden zijn alleen de relevante delen van de HTTP-headers weergegeven.

Records uit een zone opvragen

GET /dns/v1/zones/example.com/records HTTP/1.1
Host: api.nederhost.nl
Authorization: Bearer GFA7fshsaaj87FuyfSghas87ag

HTTP/1.1 200 OK

{
  "example.com": {
    "TXT": [
      {
        "id": 212422,
        "content": "\"v=spf1 -all\"",
        "ttl": 3600
      }
    ],
    "MX": [
      {
        "id": 2412421,
        "content": "10 mx-1.nederhost.nl",
        "ttl": 3600,
        "flags": [
          "managed",
          "locked"
        ]
      },
      {
        "id": 2141242,
        "content": "10 mx-2.nederhost.nl",
        "ttl": 3600,
        "flags": [
          "managed",
          "locked"
        ]
      }
    ]
  },
  "www.example.com": {
    "A": [
      {
        "id": 1245125,
        "content": "192.0.2.6",
        "ttl": 3600
      }
    ],
    "AAAA": [
      {
        "id": 124556,
        "content": "2001:db8::6",
        "ttl": 3600
      }
    ]
  }
}

In dit voorbeeld zijn de MX-records voorzien van twee flags die je kunt tegenkomen bij het opvragen van records in zones die (mede) door NederHost worden beheerd:

• managed: dit record hoort bij een hostingdienst
• locked: dit record kan niet worden gewijzigd

Het wijzigen van flags is niet mogelijk, neem eventueel contact op met NederHost voor meer informatie.

Records vervangen of toevoegen

POST /dns/v1/zones/example.com/records/www.example.com/A HTTP/1.1
Host: api.nederhost.nl
Authorization: Bearer GFA7fshsaaj87FuyfSghas87ag

[
  {
    "content": "192.0.2.8"
  }
]

HTTP 1/1 200 OK

[
  {
    "content": "192.0.2.8",
    "ttl": 3600
  }
]

In dit voorbeeld worden de records vervangen, wat betekent dat eventuele aanwezige A-records op www.example.com worden overschreven. Om alleen een extra A-record in te stellen gebruik je in plaats van POST de HTTP-method PATCH.

Records verwijderen

DELETE /v1/zones/example.com/records/www.example.com/A HTTP/1.1
Host: api.nederhost.nl
Authorization: Bearer GFA7fshsaaj87FuyfSghas87ag

HTTP/1.1 204 No Content

Dit verwijdert alle A-records op www.example.com. Bij het verwijderen van records kun je ook aangeven dat alleen records met een specifieke inhoud moeten worden verwijdert door het toevoegen van een argument 'content' aan de query:

DELETE /dns/v1/zones/example.com/records/www.example.com/A?content=192.0.2.6 HTTP/1.1
Host: api.nederhost.nl
Authorization: Bearer GFA7fshsaaj87FuyfSghas87ag

HTTP/1.1 2.04 No Content

Dit verwijdert alleen A-records die verwijzen naar 192.0.2.6.