Logo Claim_en

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/users

Explanation:

-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/domains

Response:

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

Create an user account

POST request to https://api.twodns.de/user with email and password to create an
user account.

Example:

curl -v -X POST -d ’{“email”:“joe@apiuser.de”, “password”:“mysecretpassword”}’\ https://api.twodns.de/users

Response:

POST /users HTTP/1.1 Host: https://api.twodns.de Content-Type: application/json; charset=utf-8 Status: 201 Created { “api_token”: “beb6cf5365a9fe7a56de008263dc8a9faec3d687”, “email”: “joe@apiuser.de”, “max_allowed_hosts”: 5 }
Errors:
  • Using wrong attributes to create a user account should result in 422 Unprocessable Entity response.
  • If the user account could not be created (e.g. email already exists in our
    DB), the response is 422 Unprocessable Entity followed by the errors.
    Example response message:

    • Request:

      curl -v -X POST -d ’{“email”:“invalidemail”, “password”:“mysecretpassword”}’\ https://api.twodns.de/users
    • Response:

      POST /users HTTP/1.1 Host: https://api.twodns.de Content-Type: application/json; charset=utf-8 Status: 422 Unprocessable Entity { “email”: [ “is invalid” ] }

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/me

Response:

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 of fqdn 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' as ip_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/hosts

Response:

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/hosts

Response:

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.de

Response:

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' as ip_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”: “127.0.0.1”}’ https://api.twodns.de/hosts/sub.twodns-domain.de curl -v -X PUT -u “joe@apiuser.de:42fcb5dd5f6553f90676a98523e6e22d87944c33”\ -d ’{“ip_address”: “127.0.0.1”, “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”: “81.12.12.12”}’ https://api.twodns.de/hosts/all

Response:

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.de

Response:

DELETE /hosts/my.twodns-domain.de HTTP/1.1 Host: https://api.twodns.de Status: 204 No Content

Errors & Responses Back to top

JSON Parse Error

Sending invalid JSON to the server produces a 400 Bad Request response:

POST /users HTTP/1.1 Host: https://api.twodns.de Status: 400 Bad Request Content-Type: application/json; charset=utf-8 { “message”: “JSON could not be parsed” }

Resource not found

Trying to access a resource with the wrong URL will result in a 404 Not Found
response.

GET /hosts/non.existant.de HTTP/1.1 Host: https://api.twodns.de Status: 404 Not Found Content-Type: application/json; charset=utf-8 { “message”: “Sorry, resource does not exist” }

Wrong Attributes

Sending attributes to update an object that are not included in our whitelist,
the response will be a 422 Unprocessable Entity:

POST /users HTTP/1.1 Host: https://api.twodns.de Status: 422 Unprocessable Entity Content-Type: application/json; charset=utf-8 { “message”: “JSON contains wrong attributes” }
Spinner