BuddyNS logo

BuddyNS API

BuddyNS offers a simple, powerful API to all users. This API allows you to:

Terms of Use & feedback

APIv1 was open to Advanced Users only. APIv2 is accessible to all BuddyNS users. According to our GToU, we retain rights to revoke access individually (e.g. upon resource abuse).

You need a BuddyNS user account to use the API. To get one, activate a zone on BuddyNS.

For any comment or idea, our feedback address is always open. Just drop us an e-mail!

Technical overview

We display examples using the curl command-line HTTP browser for simplicity. Obviously all queries are applicable to any alternative client (wget, python, ruby, PHP etc).

Compatibility note

This is major version v2 of the API. Within v2, new fields can be introduced in responses; existing fields and paths will not be modified.

Security and Authentication

Access methods:

  • HTTP
  • HTTPs

and we highly recommend you use HTTPs.

The API exclusively provides user-specific data. The user is authenticated with any of these mechanisms:

  • Basic HTTP authentication (for external tools)
  • API Key / Token

API Key

The API key allows every API operation (including removing zones, or changing their master) without entering the original username + password.

Use this when you need to store your API access data anywhere that could be compromised. If compromised, your original username and password remain safe. For security reasons, API Key access is disabled by default.

You can enable API Key access from your BuddyBoard. If you do, protect your API Key like a password. For the same reasons, we allow key-based API access only over HTTPs. Once enabled, Token-based authentication is performed by passing special HTTP header Authorization: Token X to the request, where X is your token as provided by the BuddyBoard.

Authentication examples

Access with Basic Authentication, when username is user@domain.com and password mypassword:

curl -u user@domain.com:mypassword -XGET https://www.buddyns.com/api/v2/zone/

Access with API Key / Token authentication, when token is 25719b77324162b3f369f27db37f41bbb5de6bd5:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/zone/

Rate limits

The API is protected by rate limits at multiple levels to ensure uptime and fair access to all users. Make sure your scripts avoid fast-rate bulks of requests at once, and large overall number of requests over a longer time span.

Field Syntactic type Semantic type
Domain / Zone name UTF-8 String RFC 3490 or IDNA
Timestamp ISO 8601 String UTC timezone
Master & Address String IPv4 or IPv6
Mobile number String ITU-T E.123

Formats & types

All request parameters are passed in standard HTTP POST format.

All responses are given in JSON format.

Types are as listed in the table.

Model and paths

The API follows the RESTful model under base URL https://www.buddyns.com/api/v2/ .

The following resources are available:

Zone

Base URL: https://www.buddyns.com/api/v2/zone/

URL GET POST PUT DELETE
/api/v2/zone/ List all zones Add a new zone. Mandatory arguments:
  • name RFC 3490
  • master
none none
/api/v2/zone/myzone.com Get configuration details:
  • name RFC 3490
  • name_idn
  • serial
  • master
  • creation_ts
none none Delete zone
/api/v2/zone/myzone.com/status/ Get status details:
  • zone RFC 3490
  • transfer_ok
  • first_failure_ts
  • last_failure_ts
  • last_success_ts
none none none
/api/v2/zone/myzone.com/delegation/ Get delegation details:
  • registry_ok
  • authority_ok
  • master_ok
none none none

Sync

Sync is a virtual resource to request SyncNOW!, that is immediate synchronization of one o more zones.

URL GET POST PUT DELETE
/api/v2/sync/ SyncNOW all zones in account none none none
/api/v2/sync/myzone.com SyncNOW myzone.com only none none none

User

Base URL: https://www.buddyns.com/api/v2/user/profile/

URL GET POST PUT DELETE
/api/v2/user/ Get essential user parameters:
  • email
none none none
/api/v2/user/profile/ Get profile parameters:
  • used_traffic
  • estimated_traffic
  • mobile_number ITU-T E.123
  • cpanel_integration
none Change parameters:
  • mobile_number ITU-T E.123
  • cpanel_integration
none

Service

Base URL: https://www.buddyns.com/api/v2/service/

URL GET POST PUT DELETE
/api/v2/service/ Get service parameters:
  • num_zones
  • traffic_quota
  • num_stats
none none none

Internationalized Domain Names

BuddyNS pioneers support for Internationalized Domain Names (those with funny characters in them). No less, this API is fully IDN-capable.

IDN names can be passed in both their UTF and ASCII forms, and this applies to both parameters and URLs.

Responses normally contain their original (end-user, UTF) representation; when details are responded, the canonical (ASCII-encoded) representation is also included.

BuddyNS is cool full-stack.

Learn by example

Create zone

Activate new zone microsoft.com (master 65.55.37.62) in account user@domain.com:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XPOST -F "name=microsoft.com" -F "master=65.55.37.62" https://www.buddyns.com/api/v2/zone/

This returns the newly added zone:

{"name": "microsoft.com", "name_idn": "microsoft.com", "serial": null, "master": "65.55.37.62", "creation_ts": "2013-11-06T19:39:38.205"}

List zones

Fetch the list of zones for account user@domain.com:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/zone/

Will respond with an array of objects:

[ {
    "name" : "microsoft.com",
    "name_idn" : "microsoft.com",
    "creation_ts" : "2013-11-06T19:39:38.205",
    "master" : "65.55.37.62",
    "serial" : 2013110601,
    "status": "/api/v2/zone/microsoft.com/status/",
    "delegation": "/api/v2/zone/microsoft.com/delegation/"
},
{
    "name" : "bücher.de",
    "name_idn" : "xn--bcher-kva.de",
    "creation_ts" : "2012-06-06T19:53:07.269",
    "master" : "154.15.200.6",
    "serial" : 1383743519,
    "status": "/api/v2/zone/bücher.de/status/",
    "delegation": "/api/v2/zone/bücher.de/delegation/"
 } ]

Removing a zone

Use the DELETE method on the zone:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XDELETE https://www.buddyns.com/api/v2/zone/myzone.com

This return no content on success. On failure, you get this error:

{"detail": "Not found"}

Updating a zone's parameters

Implement this with a chained call: delete the zone and re-add it with the new data.

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XDELETE https://www.buddyns.com/api/v2/zone/myzone.com
curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XPOST -F "name=myzone.com" -F "master=4.3.2.1" https://www.buddyns.com/api/v2/zone/

Getting zone config details

Use the /status/ URL specifier on the zone resource:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/zone/b%C3%BCcher.de/status/

The response:

{"zone": "xn--bcher-kva.de", "transfer_ok": true, "first_failure_ts": "2013-08-20T14:36:31.808", "last_failure_ts": "2013-08-20T14:36:31.808", "last_success_ts": "2013-11-07T21:59:15.581"}

Getting zone delegation details

Use the /delegation/ URL specifier on the zone resource:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/zone/b%C3%BCcher.de/delegation/

The response:

{"zone": "bücher.de", "master": "154.15.200.6", "master_ok": true, "registry_ok": true, "authority_ok": true}

SyncNOW a zone

Use the /api/v2/sync/b%C3%BCcher.de URL specifier on the syncnow resource:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/sync/b%C3%BCcher.de

On success the response has empty content.

Getting amount of traffic consumed

Simply GET the /user/profile/ resource:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/user/profile/