Domeneshop API Documentation (v0)

Download OpenAPI specification:Download

Overview

Domeneshop offers a simple, REST-based API, which currently supports the following features:

  • List domains
  • List invoices
  • Create, read, update and delete DNS records for domains
  • Create, read, update and delete HTTP forwards ("WWW forwarding") for domains
  • Dynamic DNS (DDNS) update endpoints for use in consumer routers

Authentication

The Domeneshop API currently supports only one method of authentication, HTTP Basic Auth. More authentication methods may be added in the future.

To generate credentials, visit this page after logging in to the control panel on our website:

https://www.domeneshop.no/admin?view=api

Libraries

Domeneshop maintains multiple API libraries to simplify using the API.

The libraries may be found in our Github repository.

Domeneshop also maintains a plugin for EFF's Certbot, which automates issuance and renewal of SSL-certificates on your own servers for domains that use Domeneshop's DNS service. This plugin is found in our Github repository here.

basicAuth

With the HTTP Basic Auth authentication method, the token is the username, and the secret is the password.

See above for instructions on how to generate credentials.

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Domains

List domains

Authorizations:
basicAuth
query Parameters
domain
string
Example: domain=.no

Only return domains whose domain field includes this string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find domain by ID

Authorizations:
basicAuth
path Parameters
domainId
required
integer

ID of the domain

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "domain": "example.com",
  • "expiry_date": "2019-08-24",
  • "registered_date": "2019-08-24",
  • "renew": true,
  • "registrant": "Ola Nordmann",
  • "status": "active",
  • "nameservers": [
    ],
  • "services": {
    }
}

DNS

These endpoints allow you to list, create and delete DNS records for any domain that has active DNS service.

List DNS records

Authorizations:
basicAuth
path Parameters
domainId
required
integer

ID of the domain

query Parameters
host
string
Example: host=www

Only return records whose host field matches this string

type
string
Example: type=A

Only return records whose type field matches this string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add DNS record

Authorizations:
basicAuth
path Parameters
domainId
required
integer

ID of the domain

Request Body schema: application/json
One of
host
required
string

The host/subdomain the DNS record applies to

ttl
integer <int16> [ 60 .. 604800 ]
Default: 3600

TTL of DNS record in seconds. Must be a multiple of 60.

type
required
string
Value: "A"
data
required
string <ipv4>

IPv4 address

Responses

Request samples

Content type
application/json
Example
{
  • "host": "@",
  • "ttl": 3600,
  • "type": "A",
  • "data": "192.168.0.1"
}

Response samples

Content type
application/json
{
  • "id": 1
}

Find DNS record by ID

Authorizations:
basicAuth
path Parameters
domainId
required
integer

ID of the domain

recordId
required
integer

ID of DNS record

Responses

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "host": "@",
  • "ttl": 3600,
  • "type": "A",
  • "data": "192.168.0.1"
}

Update DNS record by ID

Authorizations:
basicAuth
path Parameters
domainId
required
integer

ID of the domain

recordId
required
integer

ID of DNS record

Request Body schema: application/json
One of
host
required
string

The host/subdomain the DNS record applies to

ttl
integer <int16> [ 60 .. 604800 ]
Default: 3600

TTL of DNS record in seconds. Must be a multiple of 60.

type
required
string
Value: "A"
data
required
string <ipv4>

IPv4 address

Responses

Request samples

Content type
application/json
Example
{
  • "host": "@",
  • "ttl": 3600,
  • "type": "A",
  • "data": "192.168.0.1"
}

Delete DNS record by ID

Authorizations:
basicAuth
path Parameters
domainId
required
integer

ID of the domain

recordId
required
integer

ID of DNS record

Responses

Dynamic DDNS (DDNS)

This group exposes endpoints that can be used by certain Dynamic DNS implementations found in consumer routers appliances.

Update

Update DNS using the "IP update protocol".

A DNS record for the given hostname will be created if it does not exist, or updated if it does. The record type (A or AAAA will automatically be detected).

If the DDNS implementation does not allow you to specify authentication, it can usually be specified inline in the URL:

https://{token}:{secret}@api.domeneshop.no/v0/dyndns/update?hostname=example.com&myip=127.0.0.1
Authorizations:
basicAuth
query Parameters
hostname
required
string <hostname>
Examples:
  • hostname=www.example.com - One hostname
  • hostname=example.com,www.example.com - Multiple hostnames

The fully qualified domain (FQDN) to be updated, without trailing dot. Multiple hostnames may be provided, delimited by commas

myip
string <ipv4|ipv6>
Examples:
  • myip=127.0.0.1 - One IP
  • myip=127.0.0.1,2001:db8::1 - Multiple IPs

The new IPv4 or IPv6 address to set. If not provided, the IP of the client making the API request will be used. Multiple IPv4 and IPv6 addresses (up to 9) can be provided, delimited by commas.

Responses

HTTP Forwards

These endpoints allow you to list, create and delete HTTP forwards ("WWW forwarding") for any domain that has active DNS service.

While frame forwards (an <iframe> embed) are supported through setting the frame field, we strongly discourage the use of these. Use DNS records instead.

List forwards

List all forwards for the specified domain.

Authorizations:
basicAuth
path Parameters
domainId
required
integer

ID of the domain

Responses

Response samples

Content type
application/json
[]

Add forward

Create a forwarding for the specified domain, to a given URL.

The forward must not collide with any existing forwarding or DNS record of types A, AAAA, ANAME or CNAME.

Authorizations:
basicAuth
path Parameters
domainId
required
integer

ID of the domain

Responses

Find forward by host

Authorizations:
basicAuth
path Parameters
domainId
required
integer

ID of the domain

host
required
string
Example: www

Subdomain of the forward, @ for the root domain

Responses

Response samples

Content type
application/json
{}

Update forward by host

Update a forwarding for the specified domain, to a given URL.

The host field must not be changed. In that case, delete the existing forwarding and recreate it for the new host/subdomain.

Authorizations:
basicAuth
path Parameters
domainId
required
integer

ID of the domain

host
required
string
Example: www

Subdomain of the forward, @ for the root domain

Request Body schema: application/json
host
string

The subdomain this forward applies to, without the domain part.

For instance, www in the context of the example.com domain signifies a forward for www.example.com.

frame
boolean

Whether to enable frame forwarding using an iframe embed. NOT recommended for a variety of reasons.

url
string

The URL to forward to. Must include scheme, e.g. https:// or ftp://.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete forward by host

Authorizations:
basicAuth
path Parameters
domainId
required
integer

ID of the domain

host
required
string
Example: www

Subdomain of the forward, @ for the root domain

Responses

Invoices

List invoices

List invoices for your account. Only invoices from the past 3 years are returned.

Authorizations:
basicAuth
query Parameters
status
string
Enum: "unpaid" "paid" "settled"
Example: status=paid

Only return invoices with this status

Responses

Response samples

Content type
application/json
[]

Find invoice by invoice number

Authorizations:
basicAuth
path Parameters
invoiceId
required
integer

An invoice number

Responses

Response samples

Content type
application/json
{}

DNS record models

These are the schema definitions for the different valid DNS record types.

A record

id
required
integer

ID of DNS record

host
required
string

The host/subdomain the DNS record applies to

ttl
integer <int16> [ 60 .. 604800 ]
Default: 3600

TTL of DNS record in seconds. Must be a multiple of 60.

type
required
string
Value: "A"
data
required
string <ipv4>

IPv4 address

{
  • "id": 1,
  • "host": "@",
  • "ttl": 3600,
  • "type": "A",
  • "data": "192.168.0.1"
}

AAAA record

id
required
integer

ID of DNS record

host
required
string

The host/subdomain the DNS record applies to

ttl
integer <int16> [ 60 .. 604800 ]
Default: 3600

TTL of DNS record in seconds. Must be a multiple of 60.

type
required
string
Value: "AAAA"
data
required
string <ipv6>

IPv6 address

{
  • "id": 1,
  • "host": "@",
  • "ttl": 3600,
  • "type": "AAAA",
  • "data": "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
}

CNAME record

id
required
integer

ID of DNS record

host
required
string

The host/subdomain the DNS record applies to

ttl
integer <int16> [ 60 .. 604800 ]
Default: 3600

TTL of DNS record in seconds. Must be a multiple of 60.

type
required
string
Value: "CNAME"
data
required
string

The target hostname

{
  • "id": 1,
  • "host": "@",
  • "ttl": 3600,
  • "type": "CNAME",
  • "data": "www.example.com"
}

MX record

id
required
integer

ID of DNS record

host
required
string

The host/subdomain the DNS record applies to

ttl
integer <int16> [ 60 .. 604800 ]
Default: 3600

TTL of DNS record in seconds. Must be a multiple of 60.

type
required
string
Value: "MX"
data
required
string <hostname>

The target MX host.

priority
required
integer <int16>

MX record priority, also known as preference. Lower values are usually preferred first, but this is not guaranteed

{
  • "id": 1,
  • "host": "@",
  • "ttl": 3600,
  • "type": "MX",
  • "data": "mx.example.com",
  • "priority": 1
}

SRV record

id
required
integer

ID of DNS record

host
required
string

The host/subdomain the DNS record applies to

ttl
integer <int16> [ 60 .. 604800 ]
Default: 3600

TTL of DNS record in seconds. Must be a multiple of 60.

type
required
string
Value: "SRV"
data
required
string <hostname>

The target hostname

priority
required
integer <int16>

SRV record priority, also known as preference. Lower values are usually preferred first

weight
required
integer <int16>

SRV record weight. Relevant if multiple records have same preference

port
required
integer <int16>

SRV record port. The port where the service is found.

{
  • "id": 1,
  • "host": "@",
  • "ttl": 3600,
  • "type": "SRV",
  • "data": "www.example.com",
  • "priority": 10,
  • "weight": 100,
  • "port": 443
}

TXT record

id
required
integer

ID of DNS record

host
required
string

The host/subdomain the DNS record applies to

ttl
integer <int16> [ 60 .. 604800 ]
Default: 3600

TTL of DNS record in seconds. Must be a multiple of 60.

type
required
string
Value: "TXT"
data
required
string

Freeform text field.

{
  • "id": 1,
  • "host": "@",
  • "ttl": 3600,
  • "type": "TXT",
  • "data": "v=spf1 include:_spf.domeneshop.no ~all"
}