Two-DNS API v2
You can use our API to access the services Two-DNS provides. The following requirements have to be met:
Confirmed user account
After you sign up (either via API or the website) you have to confirm your user account via the link in the email you got after registration.
API token
The private services of the API are secured with HTTP Basic Authentication. In order to access them you have to provide the email address associated with your user account als username and the API token you receive after signing up as password.
Authentication Back to top
In order to use some of the services the API offers you have to authenticate with your registered e-mail address and the API token you can find in your Dashboard under “API Token”.
The authentication method is HTTP Basic Authentication. Normally you would use your username and your password when using HTTP Basic Auth. To access the Two-DNS.de API your username is your e-mail address and the password is your API token. The API token is a security measure: as soon as it’s contaminated, e.g. a third person has seen it, you can request a new token in your dashboard, to which a person that only has the token doesn’t have access to. After requesting a new token the old one is invalid and doesn’t offer the possibility to access your data via the API.
There is absolutely no need to send your password to the API. The only exception to this is rule is when you create an account. But don’t worry: the API is secured with SSL.
Example:
Creating hosts is a non-public service of the API. In order to create a host, you have to authenticate with your e-mail address and your API token.
Let’s create a host with the name subdomain
for the domain twodns.de
. I need to provide some additional information too: ttl
, ip_address
and whether or not I want to activate_wildcard
for this host.
Using the command line tool curl I need to provide the following parameters in order to create a host:
curl -X POST –user “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ –data ’{“hostname”:“subdomain”, “ip_address”:“91.181.24.121”, “ttl”:“14400”,\ “activate_wildcard”:“true”, “domainname”:“twodns.de” }’ https://api.twodns.de/usersExplanation:
-u/--user
: tells curl to use HTTP Basic Auth. As said before: We use the e-mail address and the API token as the username/password pair.
-d/--data
: required in order to send the attributes of the host we want to create to the API.
Domains Back to top
Get domains index
GET
request to https://api.twodns.de/domains
to get a listing of all available domain names.
Example:
curl -X GET https://api.twodns.de/domainsResponse:
GET /domains HTTP/1.1 Host: https://api.twodns.de Content-Type: application/json; charset=utf-8 Status: 200 OK [ { “name”: “twodns-domain.de” }, { “name”: “twodns.de” } ]User Account Back to top
Get info about your own user account
Authentication required:
GET
request to https://api.twodns.de/users/me
to see information about your user account.
Example:
curl -v -X GET -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ https://api.twodns.de/users/meResponse:
GET /users/me HTTP/1.1 Host: https://api.twodns.de Status: 200 OK Content-Type: application/json; charset=utf-8 { “api_token”: “42fcb5dd5f6553f90676a98523e6e22d87944c33”, “email”: “joe@apiuser.de”, “max_allowed_hosts”: 5, “hosts”: [ { “activate_wildcard”: true, “fqdn”: “my.twodns-domain.de”, “ip_address”: “81.12.12.12”, “ttl”: 14400 }, { “activate_wildcard”: true, “fqdn”: “doodeeloo.twodns-domain.de”, “ip_address”: “81.12.12.12”, “ttl”: 14400 } ] }Hosts Back to top
Create a host
Authentication required:
POST
request to https://api.twodns.de/hosts
with hostname
, ip_address
, ttl
, activate_wildcard
and domainname
as data.
Request data:
-
fqdn
(String)Possible values:
[yourhost].[domain]
You can get an index of all available domains by sending a
GET
request to
twodns.de/api/domains
Example:
If you want to create a host with name ‘myserver’ for the domain 'twodns.de’
the value offqdn
should be'myserver.twodns.de'
. -
ip_address
(String)Possible values:
-
'81.121.90.105'
(e.g.) – Any IP address you want to your host to point to. -
'auto'
– If you send a request to update one of your hosts to have'auto'
asip_address
the server automatically sets the hosts IP to the requesting clients IP.
-
-
ttl
(Integer)Possible values:
60
-
300
, -
14400
, 86400
activate_wildcard
(Boolean)
Example:
curl -v -X POST -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ -d ’{“fqdn”: “sub.twodns-domain.de”, “ip_address”: “192.168.0.1”, “ttl”: “60”,\ “activate_wildcard”: “true”}’ https://api.twodns.de/hostsResponse:
POST /hosts HTTP/1.1 Host: https://api.twodns.de Status: 201 Created Content-Type: application/json; charset=utf-8 { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “sub.twodns-domain.de”, “ip_address”: “192.168.0.1”, “url”: “https://api.twodns.de/hosts/sub.twodns-domain.de” }Errors:
- Using wrong attributes to create a host should result in
422 Unprocessable Entity
response. -
If the host could not be created (e.g. hostname already exists), the response is
422 Unprocessable Entity
followed by the errors.
Example response message:-
Request:
curl -v -X POST -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ -d ’{“fqdn”:“sub.twodns-domain.de”, “ip_address”: “192.168.0.1”, “ttl”: “60”,\ “activate_wildcard”: “true”}’ https://api.twodns.de/hosts -
Response:
POST /hosts HTTP/1.1 Host: https://api.twodns.de Status: 422 Content-Type: application/json; charset=utf-8 { “hostname”: [ “has already been taken” ] }
-
Get info about all your hosts
Authentication required:
GET
request to https://api.twodns.de/hosts
to see information of all hosts.
Example:
curl -v -X GET -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ https://api.twodns.de/hostsResponse:
GET /hosts HTTP/1.1 Host: https://api.twodns.de Status: 200 OK Content-Type: application/json; charset=utf-8 [ { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “sub.twodns-domain.de”, “ip_address”: “192.168.0.1”, “url”: “https://api.twodns.de/hosts/sub.twodns-domain.de” }, { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “mywan.twodns-domain.de”, “ip_address”: “192.168.0.1”, “url”: “https://api.twodns.de/hosts/mywan.twodns-domain.de” } ]Get info about one of your hosts
Authentication required:
GET
request to https://api.twodns.de/hosts/[host_fqdn]
to see information about one specific host.
Example:
curl -v -X GET -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ https://api.twodns.de/hosts/sub.twodns-domain.deResponse:
GET /hosts/sub.twodns-domain.de HTTP/1.1 Host: https://api.twodns.de Status: 200 OK Content-Type: application/json; charset=utf-8 { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “sub.twodns-domain.de”, “ip_address”: “192.168.0.1”, “url”: “https://api.twodns.de/hosts/sub.twodns-domain.de” }Updating a host
Authentication required:
PUT
request to https://api.twodns.de/hosts/[host_fqdn]
.
Request data:
-
ip_address
(String)Possible values:
-
'81.121.90.105'
(e.g.) – Any IP address you want to your host to point to. -
'auto'
– If you send a request to update one of your hosts to have'auto'
asip_address
the server automatically sets the hosts IP to the requesting clients IP.
-
-
ttl
(Integer)Possible values:
60
-
300
, -
14400
, 86400
activate_wildcard
(Boolean)
You can update one or all of the named attributes with one request.
If you try to update an attribute that is not included in this whitelist, you’ll get an 422 Unprocessable Entity
response. See Errors.
Examples:
curl -v -X PUT -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33” -d ’{“ip_address”: “auto”}’ https://api.twodns.de/hosts/sub.twodns-domain.decurl -v -X PUT -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33” -d ’{“ip_address”: “auto”, “activate_wildcard”: “true”}’ https://api.twodns.de/hosts/sub.twodns-domain.de
Response:
PUT /hosts/sub.twodns-domain.de HTTP/1.1 Host: https://api.twodns.de Status: 200 OK Content-Type: application/json; charset=utf-8 [ { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “sub.twodns-domain.de”, “ip_address”: “127.0.0.1”, “url”: “https://api.twodns.de/hosts/sub.twodns-domain.de” } ]Updating all hosts:
Authentication required:
Nearly the same as updating a single host, except that the [host_fqdn]
at the end of the URL should be all
:
PUT
request to https://api.twodns.de/hosts/all
.
Example:
curl -v -X PUT -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33” -d ’{“ip_address”: “auto”, “activate_wildcard”: “true”}’ https://api.twodns.de/hosts/allResponse:
PUT /hosts/all HTTP/1.1 Host: https://api.twodns.de Status: 200 OK Content-Type: application/json; charset=utf-8 [ { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “sub.twodns-domain.de”, “ip_address”: “127.0.0.1”, “url”: “https://api.twodns.de/hosts/sub.twodns-domain.de” }, { “activate_wildcard”: true, “ttl”: 60, “fqdn”: “mywan.twodns-domain.de”, “ip_address”: “127.0.0.1”, “url”: “https://api.twodns.de/hosts/mywan.twodns-domain.de” } ]Deleting a host
DELETE
request to https://api.twodns.de/hosts/[host_fqdn]
: the server answers with a 204 No Content
response, if the host has been deleted
Example:
curl -v -X DELETE -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ https://api.twodns.de/hosts/my.twodns-domain.deResponse:
DELETE /hosts/my.twodns-domain.de HTTP/1.1 Host: https://api.twodns.de Status: 204 No ContentErrors & Responses Back to top
JSON Parse Error
Sending invalid JSON to the server produces a 400 Bad Request
response:
Resource not found
Trying to access a resource with the wrong URL will result in a 404 Not Found
response.
Wrong Attributes
Sending attributes to update an object that are not included in our whitelist,
the response will be a 422 Unprocessable Entity
: