REST DNS-API
Met de REST DNS-API kun je DNS-records op je domeinnaam volledig geautomatiseerd beheren vanuit je eigen software.
Inhoud
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.